Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Posting-Version: version B 2.10.1 6/24/83; site ncsu.UUCP
Path: utzoo!linus!philabs!cmcl2!seismo!harvard!talcott!panda!genrad!decvax!mcnc!ncsu!mauney
From: mauney@ncsu.UUCP (Jon Mauney)
Newsgroups: net.lang.c
Subject: Re: Style, readability, etc. (use of comments)
Message-ID: <2904@ncsu.UUCP>
Date: Fri, 26-Jul-85 11:11:17 EDT
Article-I.D.: ncsu.2904
Posted: Fri Jul 26 11:11:17 1985
Date-Received: Sun, 28-Jul-85 07:42:48 EDT
References: <95@brl-tgr.ARPA>, <1207@sjuvax.UUCP>
Organization: N.C. State University, Raleigh
Lines: 39

> From: jss@sjuvax.UUCP (J. Shapiro)
> Subject: Re: Style, readability, etc. (long, but IMPORTANT)
> Message-ID: <1207@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."