People say that 'code should be commented' like writing good comments is
easy.  In fact, writing good comments isn't easy at all, and bad comments
can be worse than no comments at all.  I don't know how often I've gone back
and looked at old code (of my own!) to find that I didn't comment the part
that was now mysterious, or that I documented HOW it worked but not WHY I
was doing that, or that I documented WHY I was doing something, but didn't
give a clue as to HOW the code was supposed to accomplish that.

This gets worse - MUCH worse - when multiple people are working on the same
code.  It doesn't count the times that comments were (probably) long since
obsolete (but no one was SURE enough to remove or change them) or comments
that don't match the code at all (someone changed code but not the comment,
or the code was just wrong, and people believed the comment.)  It doesn't
count the times code was cut-and-pasted into a new location with the old
comments.  It doesn't count function names and comment references that were
obvious in the context of the original authors, but are so much babble to
the newer programmers from a different context (what do you think "bones()"
does, and how do you pronounce it, if it's primarilly used in process death
code?  What if it's defined next to "bzero()"?  Do you know what "edisms()"
is likely to do, and how is IT pronounced?)

(all these examples were from C code, BTW.  It'd be worse in assembler.)

I've seen WAY too many "verbosely commented" examples of code that didn't
tell me what I was reading them to find out.  Any attempt to ENFORCE "good"
comments inevitably fails, because writing good comments is HARD, and the
definition of "good" is invariably variable.

BillW