The Futility of Commenting Code
lingpipe-blog.com
lingpipe-blog.com
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.
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.