Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Posting-Version: version B 2.10.2 9/18/84; site ncr-sd.UUCP
Path: utzoo!linus!philabs!cmcl2!seismo!harvard!talcott!panda!genrad!decvax!ittatc!dcdwest!sdcsvax!ncr-sd!tien
From: tien@ncr-sd.UUCP (Tien Nguyen)
Newsgroups: net.lang.c
Subject: Re: Style, readability, etc. (long, but IMPORTANT)
Message-ID: <256@ncr-sd.UUCP>
Date: Wed, 7-Aug-85 19:34:33 EDT
Article-I.D.: ncr-sd.256
Posted: Wed Aug  7 19:34:33 1985
Date-Received: Mon, 12-Aug-85 03:14:13 EDT
References: <95@brl-tgr.ARPA>
Reply-To: tien@ncr-sd.UUCP (0000-Tien Nguyen)
Organization: NCR Corporation, Torrey Pines
Lines: 25

In article <95@brl-tgr.ARPA> DHowell.ES@Xerox.ARPA writes:
>But even more helpful even for C programmers is a comment
>explaining why you are incrementing the variable, such as
>
>  fish++;  /* we found another fish, so increment the fish counter */
> 
>  ptr++;  /* increment the pointer to the next element */
>  i++;  /* increment i */
>
The first comment is 'good' since it explains why we want to increment
the fish counter--found another fish.  However, the next two comments
are irrelevant.  The reason is if the reader does not know what i++
means then he/she could always look at any C book once and from then
on he/she will know that i++ is i=i+1 thus we don't need to add the
comment /* increment xx */ all over our program.  However, the comment,
if any, should explain why we want to increment i or ptr.

In my opinion, the comment should tell the reader WHY and WHAT we are doing
rather than to explain the language syntax.  I would have put the same
comment on the fish++ statement even if I wrote it in form:

			fish = fish + 1;


					Tien Nguyen,