Don't Waste Your Time Commenting Source Code

I recently had an argument with a colleague about source code comments. He called it one of software development best practices and suggested that any programmer worth his salt writes extensive comments. You hear this pretty often from people who consider themselves "old school". Well, I have been writing code since early 90s, but I strongly believe that 90% of source code comments are a waste of time. Let's review the arguments...

Pro: Comments explain what the program does, so the person maintaining the code can understand it easily.

Well, it sounds good on the surface, but if you think about it, a well-designed program doesn't need comments to be maintainable. A well-designed program uses classes and design patterns; it has high cohesion, low coupling, and limited cyclomatic complexity. The names of classes and variables are carefully chosen to be self-explanatory. We know that programmers don't generally have unlimited time for development. If the choice is between a well-designed program without comments and a thoroughly commented but poorly architected one, I will choose the former any day of the week. Frankly, I would rather have developers spend time polishing their design skills than technical writing skills.

Contra: Automated unit tests explain what the program does just as well, and they never become obsolete.

The truth about source code comments, and any written documentation for that matter, is that it quickly becomes obsolete. Take a look at this real-life example I took from StackOverflow discussion:

/**
 * Always returns true.
 */
public boolean isAvailable() {
    return false;
}

There is no guarantee that the person changing the code will take time to update the comment. There is nothing your integration server can do to enforce this. On the other hand, consider this unit test:

var result = myobject.isAvailable();
Assert.IsTrue(result);

As soon as someone changes the method to return "false" instead of "true" and checks the code in, the unit test will break on next build, and pretty soon the developer will be looking into the issue.

Contra: What makes you think people can write clearly?

Let's face it, not every programmer can write well in English (that goes without saying for us immigrants, but I have seen comments written by native English speakers that were profoundly confusing). On the other hand, unit tests are written in programming languages, so developers can apply their core competencies. Natural language comments can be ambiguous, vague, sarcastic, or humorous. Some may be even fun to read (that StackOverflow discussion has some real gems!), but unit tests are much more practical - they leave no room for different interpretations.

Pro: Sometimes you just need to leave a note...

This is the only case that I would concede. Here is an example to illustrate this point:

// 
// Dear maintainer:
// 
// Once you are done trying to 'optimize' this routine,
// and have realized what a terrible mistake that was,
// please increment the following counter as a warning
// to the next guy:
// 
// total_hours_wasted_here = 39
//