Style, readability, etc. (use of comments)

[Jon Mauney]

> From: jss at sjuvax.UUCP (J. Shapiro)
> Subject: Re: Style, readability, etc. (long, but IMPORTANT)
> Message-ID: <1207 at sjuvax.UUCP>
>   
> > while(ptr++->duck)  /* move pointer to the duck after the next NULL */
> >   ;
> 
> This one is even more obscure than the last.  I am a C programmer, and
> this tells me nothing - indeed it is dead wrong, as it simply will not
> happen as the comment might lead me to believe.  This will leave me
> with ptr pointing to the next available record whose element named
> duck is 0.  It certainly has nothing to do with NULL or anything after
> duck.  This is one of the major difficulties with such comments.
> There is a tendency even among experienced programmers to read them
> and believe them, and thereby not see an obvious difficulty.
> 
> Jonathan S. Shapiro
> Haverford College
> ..!sjuvax!jss
> 

Let me first point out that I agree that block comments are generally
more useful than end-of-line comments.  However, there are many places
in which an end-of-line comment is very useful.  The present example
is one, as proved by the fact that apparently experienced C programmers
cannot agree on the effect of the loop.  Code that is so susceptible to
error should be avoided or heavily commented.

I look at comments as recording the programmer's *intent*, whereas the
code is (obviously) what he actually *did*.  Reading the comments tells
me whether the bug is likely due to a poor design.  If the design
seems sound, then I look for discrepancies between code and comments.
Any such discrepancy is a clear indication of a problem, although the
problem may be as simple as a slip of the mind.  Comments add redundancy
to a program, and redundancy is A Good Thing, in moderation.
-- 

Jon Mauney,    mcnc!ncsu!mauney       "The door's not shut on my genius, but...
North Carolina State University        I just don't have the time."