

The Futility of Commenting Code - tel
http://lingpipe-blog.com/2009/10/15/the-futility-of-commenting-code/

======
makecheck
He seems to believe that the only reason for a comment is to describe what
something does, and thus clearly-written code would be equivalent. If that
were strictly true, he may be right.

However, a major benefit of comments is to explain _why_ something is done a
certain way. Is anything temporary or arbitrary? Is there something counting
on a side effect? Is something being bypassed for efficiency? How will this
null argument to a function be interpreted? Is something not being checked
because it is assumed to have been validated earlier? And so forth.

~~~
mahmud
As an exception to every rule. My comments describe _unimplemented_ features!

I usually paste a huge spec document into emacs, comment it all out, and then
rearrange it to smaller parts and implement those. As time passes, the one
page is split into multiple pages and it becomes a project. Wherever there is
a big chunk of comments, it something I haven't implemented yet.

