Path: utzoo!utgpu!attcan!uunet!husc6!mailrus!uwmcsd1!csd4.milw.wisc.edu!markh
From: markh@csd4.milw.wisc.edu (Mark William Hopkins)
Newsgroups: comp.lang.pascal
Subject: Comment Pollution
Message-ID: <6508@uwmcsd1.UUCP>
Date: 16 Aug 88 00:43:23 GMT
Sender: daemon@uwmcsd1.UUCP
Reply-To: markh@csd4.milw.wisc.edu (Mark William Hopkins)
Organization: University of Wisconsin-Milwaukee
Lines: 92


     This is a new term to describe the experience I've had to go through
in going through several dozen kilobytes of programs over the last few days.
I would like to get my hands on the guy who said that you can never put too
many comments in your code.

     What I've found is that comments are often used to compensate for bad
programming in the following ways:

     (1) Bad variable naming (too cryptic or named in a way unrelated to its 
	 use.) -- thus making those otherwise unnecessary comments on the
	 variables use necessary.

The rule of thumb is:
	 If you've found it necessary to comment on the use of a variable
	 then you've given it the wrong name.

     (2) Hyfalutenated code, like this:

	 if A = 0 then Flag := true else Flag := false
	 {Flag is the condition that A is 0.}

	 Just write
	      Flag := (A = 0)
         and let the code speak for itself (or better yet, don't use a flag).
      
There's other examples more tangled than this, but this is the first and 
foremost one that comes to mind.

     (3) Bad formatting, like this:

	 while I < 0 do
	    begin
	       for I := 1 to 6 do
		 begin
                   read(A[I])
                 end; {for loop}
                readln;
            end {while loop}

I took a small example here, but imagine that this were a huge nested loop.
Imagine how much the formatting is compounding the problem of recognition
where all you are really saying is this:

	 while I < 0 do begin
	    for I := 1 to 6 do read(A[I]);
	    readln
         end

It makes it utterly unnecessary to indicate what your "ends" are going with
because you can see it clearly when the code is short enough for the
"begin" and "end" to occupy the same page.

This gets me to the second rule of thumb: If you find it necessary to make
extensive comments on your program text, then you've written the program
the wrong way. Again, let the code speak for itself and keep it short and 
simple.

     (4) Bad use of variables

I've seen stuff like this:

program ...
...
<3658 variable declarations>
x: integer; {local variable used in the procedure spfxdz.}
r: integer; {a counter.}
...

(A) Look at x.  If you're going to use it as a local variable then declare it
as such and don't clutter the main program with 3658 variables.

(B) Counters should be declared to be of a subrange type, e.g.

r: 1..StringSIZE

... after all, what else are subranges for?  The fact that you declare it
this way makes the comment unnecessary and makes the program more direct
and transparent.

There's others, but the general pattern is apparent: comments are being
used extensively to compensate for bad programming.

One of the most recent programs I modified was about 9k and 450 lines long.
Now when you write long programs, a good sense of style will compel you
to add a lot of comments.  That's the problem.  The program is already
long enough as is, the extra pollution just makes it all the more obscure.

I finally got that program down to 100 lines and 2k.  There were still a
couple (appropriate) comments in it, but nothing like the cancer I had
to weed out.  And that's the point: keep your code short, simple and direct 
and let it (or I should say: GET IT TO ...) speak for itself.