Code is not self documenting

Nothing revolutionary about that statement.  Yet I keep reading the opposite on various comment threads and message boards so I thought it a good idea to explore it again.

Code is not self documenting.

The "code is self document" argument often comes up when commenting conventions, patterns and overall usage is discussed.  People who are typically against writing more than the existing set of comments will throw out the argument "if we need a comment then the code should be written to be self documenting." 

To at extent I agree with this.  Code should not be obfuscated and the usage should be clear.  I personally strive to make my implementations as clear as possible and enforce that belief on anyone who asks me for a code review. 

Yet while you can write code so that an individual algorithm or function is close to self documenting you cannot write it in such a way that it will explain it's greater purpose in a program.  Only comments can do that.  Self describing code can only describe itself, not it's purpose in the bigger picture. 

Comments serve to both 1) explain the algorithm and 2) explain the greater purpose of the algorithm in the program.

Yet people still cling to the code is self documenting mantra.  In my experience there are several reasons for this belief.   The first is that people have only worked on projects small enough that for most purposes they can be kept entirely in their mind [*].  Until you work on a big enough program #2 is not even a factory because you intimately understand how every function fits into the big picture. 

Another is that they have never worked on a project with people they weren't very familiar with.  People you don't know well or have worked with before will likely have different ways and practices of approaching a problem which you have not encountered before.  What is obvious to them won't be obvious to you.  The bridge between these approaches are comments.

I've seen DRY (don't repeat yourself) brought up as well [**].  The code clearly says what it does so adding a comment is just repeating yourself.  I find that to be patently untrue.  If we're even having the conversation then the code is clearly not self documenting.  Also in the cases when an individual function is documenting you will still run into #2. 

Commenting your code benefits both people who are reading your code and yourself.  You will eventually come to a point where you've forgotten what a particular piece of code did or how it fit into your bigger program.  Your comments will save you.

 [*] The temptation to say "kept in memory" here was huge but I avoided it.
[**] In general I think that DRY is a great approach to programming but I feel it's being taken to far here

Comments

• Anonymous
  June 09, 2008
  The comment has been removed

• Anonymous
  June 09, 2008
  The comment has been removed

• Anonymous
  June 09, 2008
  The comment has been removed

• Anonymous
  June 09, 2008
  Comments should only exist to point out what is not obvious in the code.  In any programming assignment, an assumption must be made as to the base competence of whomever will be reading the comments subsequently.  Only document that which cannot be assumed to be clear to a subsequent developer of moderate skills.

• Anonymous
  June 09, 2008
  The comment has been removed

• Anonymous
  June 09, 2008
  The comment has been removed

• Anonymous
  June 09, 2008
  I think no one really suggests to write no comments or documentation when following this mantra. Self documenting more means to express the flow of the code properly. Of course you still need documentation on the class, the module and the conceptional model of the application. But you should not clutter your code. See http://vafer.org/blog/20050323095453

• Anonymous
  June 09, 2008
  I think no one really suggests to write no comments or documentation when following this mantra. Self documenting more means to express the flow of the code properly. Of course you still need documentation on the class, the module and the conceptional model of the application. But you should not clutter your code. See http://vafer.org/blog/20050323095453

• Anonymous
  June 09, 2008
  The comment has been removed

• Anonymous
  June 10, 2008
  @Tortsen, Unfortunately I've had that very argument made to me on several occasions and the most recent of which inspired me to write this post.  I don't think this is the majority case though.

• Anonymous
  June 10, 2008
  This problem is analogue... So both : black and white are wrong, all depends on Everything

• Anonymous
  June 10, 2008
  Good code is self-documenting. No amount of commenting will help reading bad code.

• Anonymous
  June 10, 2008
  I try to name my variables appropriately so they make sense in their given context.  I find that for most obvious operations, this is sufficient.  However, there are cases where just knowing "what" is happening is not enough -- the developer needs to know "why" it is happening.  Just today I was reviewing code that I wrote nine months ago, and while the code was completely legible and all the variables had obvious names, I couldn't figure out why I had written a specific branching statement, and I had not bothered to comment it at the time, so now I'm stuck. Another good reason to comment your code is to justify changes that were made at given points in time.  On two separate occasions, my manager has asked me why certain behavior was being manifest in our application, and I was able to pull up the code and note that, in both cases, he had made the decision to implement that specific behavior (I also included the exact date in the comments to be more specific).

• Anonymous
  June 10, 2008
  The comment has been removed

• Anonymous
  June 10, 2008
  erm... I think the argument is that code should be written to be as self-documenting as possible, not that code is self-documenting.

• Anonymous
  June 11, 2008
  @M.C. I'm a huge fan of clear code and enforce that principal in my code reviews.  Just because code is not self documenting doesn't mean it can't be readable and easily understood.  Code should be both readable and documented.  

• Anonymous
  June 12, 2008
  Code is "self documenting" in at least one respect. If you replace a human driven task (say compilation, and deployment) with a programmed script. The script is typically more "self documented" than the human process (baring well established SOPs, followed precisely).