Self Documenting Code

I have come across many developers who believe that comments are not necessary to make code readable. They argue that code should document itself. By this they mean that the code you write should be clear and have good enough naming conventions such that you don't need to add extra comments to make it understandable. They say that if you feel you need to write a comment then you should rewrite the code to be more clear.

 

I agree that any code you write should be as clear and well named as possible. Comments do NOT make bad code readable. However, I do not agree that clean well written code is sufficient documentation in itself. I am not talking about simple comments like:

 /*this calls a function which calculates 
the nth fibinocci number */
int fibNum = calculateFibinocciNumber(5);

or even funnier is: ... And I have done this in the past :)

 //the owners first name
private string ownersFirstName;

 

Those comments are useless since they are just repeating what the code clearly states.

Where you really need descriptive comments are situations such as complex algorithms that the best code in the world still wouldn't make clear how it works. Or when a function is using many different objects. While you could understand what this block does after hours of tracing through all the other functions and classes of the objects it uses, it would be much more convenient to have a simple paragraph give you an overview of what it does and how it uses other those objects.

 

Another argument against the use of comments I hear is that they don't get updated when the code does. This is a problem but this is the burden of the programmer to always update the comments. Keeping your code clean and your comments in synch with your code is part of a programmers job.

 

I believe any developer who is thrown in to a large code base will agree with me on this.

So my fellow developers PLEASE both write clean code AND write relevant descriptive comments.

Comments

• Anonymous
  October 09, 2007
  PingBack from http://msdnrss.thecoderblogs.com/2007/10/09/self-documenting-code/

• Anonymous
  October 09, 2007
  Usually my code having same types of comments as you mentioned in your blog ... can you post an example for clean code and relevant descriptive comments?

• Anonymous
  October 10, 2007
  Obviously the terms "clean code" and "descriptive comments" are slightly unfair to use.  They are very generally and don't describe what they mean that well.   Clean code in my opinion is as declartive as possible.  (Think LINQ).  While its possible to get your code to be very declarative eventualy that will break down in todays languages.  You will have this lower level implementation that may need more information. A good example I think of a descriptive comment is one for a quicksort.  Let's say you have never heard of it before and you are reading someones code.  When you see Partion(Array,Left, Right) QuickSort(Left) QuickSort(Right) you can understand that its a recursive sorting algorithm.   However, when you are shown the implementation of partition you will understand the code but not why it works.  The why is not easily described in code.

• Anonymous
  October 11, 2007
  I completely agree with the Self Documenting Code posting. Below is some sample code for summing up all