Why not to comment code

If you don't think comments are necessary, see how long it takes you to find the sections of this article that deal with exercise:

http://www.lifehack.org/articles/lifestyle/freshman-15-copin...

There are two of them. I found them in under five seconds.

Now find the section of this article that talks about stock options:

http://joelonsoftware.com/articles/fog0000000056.html

Which one took longer? Which one had comments?

QED

I hate uncommented code. When reading code I want to know what the programmer is trying to achieve (which is not infrequently different from what his code actually does).

I also often find myself wanting to just get a quick overview of what's going on instead of needing to dive in to the nitty-gritty of the implementation of a given block of code. Well-written comments help me get a bird's eye view of the code.

Certainly, uncommented code which is well written is better than uncommented code which is poorly written (and arguably better even than commented code which is poorly written), but good comments only improve code.

Still, despite my disagreement with the article, I'm upvoting it, because I think it's important to discuss issues such as this.