http://www.perlmonks.org?node_id=740502


in reply to Re: Why no comments?
in thread Why no comments?

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

  1. The new purpose to which the routine was being put.
  2. 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.
  3. 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.


Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
"Science is about questioning the status quo. Questioning authority".
In the absence of evidence, opinion is indistinguishable from prejudice.