I've downvoted this post. Not because it flies in the face of everything that I've come to believe over a long (and I believe deeply thoughtful and curious) career--though it does.
But because, as with so many of these theses, it attempts to argue and convince, not on the basis of strong pro-logic, nor strong counter-argument to the opposing views. But rather on the basis of: commenting is so obviously good, that not commenting can *only* be the product of laziness and indifference; which is absolutely not the case for many of us that prefer minimal commenting.
I started my professional coding in assembler, and commenting every line. And every routine started with big, gaudy block comments detailing date, time, author, revisions and reasons, inputs, outputs, side effects, purpose, methods and references et al. Through Bliss, Fortran and C and several others, the level of commenting slowly reduced. Not because I was too lazy to comment, but because as I went back to maintain code--my own and others--I found that the comments were inaccurate, unhelpful or misleading. And sometimes all three.
Comments made by the original authors--including myself--no longer made sense in the light of
- The new purpose to which the routine was being put.
- My new level of understanding of the purpose of the routine in the calling code, or my better understanding of the problem the code is to address in the light of the bugs that it accumulated in use.
- The fading of the memory (or no knowledge at all of it), of the mindset of the author when the code was written.
In a nutshell: things that seemed important to the author when writing the particular line, block or subroutine, are no longer significant once the intensity of thought about those lines is no longer fresh in your mind and you are instead caught up in the malaise of the bigger picture. Comments that made sense in the light of a library routine's place in one project, no longer have any significance when that library is re-used in another.
You make some claims for the advantages of "good commenting". So, I raise you a challenge. Show us an example! And let us pick over its bones. It could be very enlightening.
|Replies are listed 'Best First'.|
Re^3: Why no comments?
by gone2015 (Deacon) on Feb 01, 2009 at 21:28 UTC