Style, readability, etc. (long, but IMPORTANT)

[Tien Nguyen]

In article <95 at brl-tgr.ARPA> DHowell.ES at 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,