Path: utzoo!mnetor!uunet!husc6!cca!g-rh
From: g-rh@cca.CCA.COM (Richard Harter)
Newsgroups: comp.lang.misc
Subject: Re: Comments ( was Re: Readable Names )
Message-ID: <26189@cca.CCA.COM>
Date: 28 Mar 88 17:01:01 GMT
References: <2857@enea.se> <25668@cca.CCA.COM> <200@lclark.UUCP>
Reply-To: g-rh@CCA.CCA.COM.UUCP (Richard Harter)
Organization: Computer Corp. of America, Cambridge, MA
Lines: 42
Keywords: comments

In article <200@lclark.UUCP> dan@lclark.UUCP (Dan Revel) writes:

	... re remarks of mine about commenting every line of code

>I much prefer the latter style of commenting.  A single comment describing
>what the next block of code is going to do, instead of a comment on every
>line.  Some lines don't deserve comments, and some comments degenerate into
>stating the obvious ( increment counter, or something like that ).

	Commenting every line is not a substitute for commenting blocks
of code -- it is a separate and additional type of commenting with a 
different function.  The block prolog describes generally what is going
on in the block (block in the sense of a signifigant group of statements).

	I am not advocating commenting each line as a universal policy;
however I will give my experiences and conclusions.  The first is that
once you have adopted the style, you find yourself becoming quite compulsive
about it.  The code doesn't 'look right' without annotation.  The second is
that it 'decryptifies the code'.  We have all had the experience of looking
at code, whether your own or someone else's and wondering what is going
on.  The line comment tells you what the author intended that line of
code to do.  Example:

  xp = xp->link;                        /* Fetch next foobaz link    */

versus

  foobaz_instance = foobaz_instance->link;

Everyone, I will suppose, will agree that foobaz_instance is a more meaningful
name than xp.  However the comment tells, to some extent, what the statement
is supposed to do.  It is also a permanent record of what the statement does,
which saves you deciphering the code when you are modifying it.

	There is a more subtle benefit of commenting every line which is
not obvious -- it forces you to explain, at the time that you write it,
what you meant the statement to do!
-- 

In the fields of Hell where the grass grows high
Are the graves of dreams allowed to die.
	Richard Harter, SMDS  Inc.