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,