I was recently discussing the value of comments in code with some colleagues. After the discussion, one of them sent me a link to "Don't Waste Your Time Commenting Source Code" written by Riyad Mammadov.

I have to say I'm both shocked and disappointed that there are developers out there that have this opinion. And there seems to be quite a lot of them. I'm quite passionate about code comments because I spend the huge majority of my time maintaining/debugging/fixing code written by other people that has no comments (other than commented out code...). I waste an enormous amount of time stepping through code with a debugger, just trying to understand WTF it's trying to do.

I know some developers that always respond "The code is self-explanatory". This is a garbage excuse from a lazy programmer. There are a few reasons why this argument is not valid:

  1. It might be self-explanatory to you, but there are other developers here that may need to maintain your code, some less skilled than others.
  2. Unless you're a compiler, reading an English comment is far quicker than parsing code in your head.
  3. It's rarely clear from code why it does what it does.
  4. Reading code only helps you understand what it does, not what it was intended to do. This would be fine if you wrote flawless code. You don't.

In addition to this, we often have to write less-than-ideal code. You might find a bug, and to work around it, change some nice clean code to something a little bit hacky. If you don't comment why, there are good chances that someone will come along, think "WTF, this could be done better" and refactor your code, re-introducding the bug. A simple comment saying "Can't do this using X, because it causes Y to fail" could save a lot of time and effort.

Back to some of the points made in Riyad's article...

I strongly believe that 90% of source code comments are a waste of time

I think Riyad is a little confused between code with crap comments, and code that doesn't need commenting. I can't possible agree that only 10% of all code written is worth commenting. I might agree that only 10% of code comments are useful, but that just means the developers are failing at writing good comments, not that the idea of writing comments is bad. A huge portion of useless comments on code could be replaced with useful comments.

if you think about it, a well-designed program doesn't need comments to be maintainable

This really is tripe. Code does not convey the *reason* you are writing it. Here's an example from some real code:

// When the transition finishes, hide the screen. We don't remove it,
// because we want it to come back when the covering screen is dismissed
this.ScreenState = ScreenState.Hidden;

Without the comment, it might not be clear why the screen is being hidden, instead of being removed. Somebody that's not familiar with the code (which, six months after it being written, is everybody, including the author). The comment makes this pretty clear why the code does what it does.

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

I don't understand the logic here. There is some suggestion that writing comments comes with a penalty that somehow affects the architecture of your system. I think a more valid comparison whould be "Unfinished, but commented code" vs "Finished, but uncommented code", and I would absolutely take the commented code any day. It's unlikely that it'd take longer to finish a well written, well commented application than it would to try and understand thousands of lines of uncommented code.

Riyad shows some sample code to illustrate his point:

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

There's no argument here. This comment is pointless. However, there's some suggestion that because this comment is pointless, this code does not need commenting. That is absolutely not the case. The comment is crap. It should be replaced with one that is not crap.

Not writing code comments because some people write crap comments is like not writing code because some people write crap code.

Sadly the biggest loser in all this is not the developer that's not writing comments, but his colleagues. They'll struggle to maintain his uncommented code while he easily understands their well-commented code :(