Path: utzoo!utgpu!jarvis.csri.toronto.edu!mailrus!bbn!mit-eddie!apollo!perry
From: perry@apollo.COM (Jim Perry)
Newsgroups: comp.software-eng
Subject: Re: comments on comments
Keywords: comments
Message-ID: <4173bd76.183dc@apollo.COM>
Date: 13 Feb 89 17:31:00 GMT
References: <1813@goofy.megatest.UUCP> <20233@agate.BERKELEY.EDU>
Reply-To: perry@capsicum.UUCP (Jim Perry)
Organization: Apollo Computer, Chelmsford, MA
Lines: 62

In article <20233@agate.BERKELEY.EDU> hughes@math.Berkeley.EDU (eric hughes) writes:
>In article <1813@goofy.megatest.UUCP>, djones@megatest (Dave Jones) writes:
>
>>				   Comments which assert
>>the obvious are just clutter, worse than nothing.
>
>I have found that my grasp on the obvious is not what I
>think it is. :-)  My rule of thumb is not to comment anything
>which is implicit in the syntax of a statement, but I will 
>sometimes comment on the semantics (especially in the case of
>function calls) and always on the pragmatics (what effect it
>has).
>
>I had a friend once who was taking an assembly language class
>where the teacher required every program line to be commented.
>He wrote a filter to translate every instruction into it English
>equivalent and present it as a comment on that line.
>
>	LOAD AX, 1		; load the register AX with the value 1
>
>The teacher was satisfied and the student got good scores
>on his programs.  This is the kind of syntax-based comment I
>avoid.
>

Let me begin by saying that I'm in the camp calling for more comments.
Especially in the Unix/C world, the overwhelmingly vast majority of
programs are undercommented.  It's interesting that some aspects of
programming style, e.g. indentation, are fairly consistently applied,
while adequate documentation is the remote exception.

In your example, the chances are that there is some meaningful piece of
information that could have been conveyed -- "start with the first 
widget" -- rather than restating the language-level semantics.  [Did
you ever see this friend's filter?  I suspect this is an urban myth, as
rumors of such "tools" was common (at Dartmouth, and I'm guessing elsewhere)
in the mid-to-late '70's.]

Consider writing such a filter for C programs.  C crams so much stuff into 
a small area that just expressing what's going on, in English, would
generate huge comments.  I consider this very fact an argument for the
programmer taking the time to construct a pithy description of what a piece
of code is intended to do.  And I do, by and large, comment every line.

Code should be self-documenting, at all levels.  The main body of a program
should explain what the program does, what the dependencies, files, etc.
are, and so on.  The data declarations should explain what the data
structures are and how they are used.  Functions, modules, procedures,
macros, etc. should also explain themselves, and so on.  This is part of
what differentiates engineering from hacking.  (The comment-generating
program might be the ultimate in hackery, in this context).

I would have to say that with the possible exception of some overzealous
undergraduate student projects, I've never seen an overdocumented program,
and I've seen a vast, vast number of underdocumented ones.  I've seen some
poorly though verbosely documented ones, as discussed here and elsewhere
not all programmers have great communication skills, but never has this
been "worse than nothing".  
-- 
Jim Perry   perry@apollo.com    Apollo Computer, Chelmsford MA
This particularly rapid unintelligible patter isn't generally heard
and if it is it doesn't matter.