Re: Programming *is* much more than "just writing code".

[GrandFather]

It seems to me that there are two programming modes: green fields and maintenance, and that their commenting requirements are different. In the green fields mode I emphatically agree with the assertion that less is better wrt comments. However, in maintenance mode comments are often the most valuable contribution to the code that you can make for a number of reasons:

1. to correlate a bug with a code change
2. if today's maintainer needed large effort to understand the code so most likely will tomorrow's
3. a maintainer is often better placed to see where a comment provides the most bang for a buck
4. (sometimes) to distinguish a maintenance change from original code
5. (sometimes) to elucidate the maintainer's understanding of the code

That is not to say that every changed line of code requires a comment or that every comment should be a story that includes the maintainers state of mind and how much coffee had been consumed. The rules for succint and sparse commenting still apply but the bar is lowered somewhat in light of a need to compensate for deficiencies (perceived or otherwise) in the original code. The alternative may often be a completely impractical refactorisation of the code.

If a back story is required for the code changes, that should be in the bug tracking system with a synopsis in the check in comment in the revision control system.

If even half an hour is spent trying to understand a section of code, and that investigation could be averted in the future by addition of a brief comment, then the comment is a good investment. Most times just a couple of words is enough to provide the hint required for understanding. Anything more than a few words should point to documentation elsewhere - five minutes reading documentation is still way better than a half hour investigation.

Non-trivial bug fixes require a higher degree of commenting simply because, if the issue wasn't obvious to the original programmer, it probably won't be obvious to whomever follows.

Very nice node btw!