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.