Path: utzoo!attcan!uunet!husc6!bu-cs!buengc!art
From: art@buengc.BU.EDU (A. R. Thompson)
Newsgroups: comp.lang.pascal
Subject: Re: Comment Pollution
Message-ID: <840@buengc.BU.EDU>
Date: 16 Aug 88 19:26:23 GMT
References: <6508@uwmcsd1.UUCP>
Reply-To: art@buengc.bu.edu (A. R. Thompson)
Followup-To: comp.lang.pascal
Organization: Boston Univ. Col. of Eng.
Lines: 99

In article <6508@uwmcsd1.UUCP> markh@csd4.milw.wisc.edu (Mark William Hopkins) writes:
>
>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.

This does not always work a neatly as we would like.  Once, several years
ago, I and a colleague were working on a Pascal compiler that was to
implement the (then) proposed standard.  Instead of starting from scratch,
we modified an existing compiler.  There was a boolean variable spelled
"ttyinuse".  Upon reading the code we discovered that when the variable
"ttyinuse" was true the tty was NOT in use!

I'm not arguing in favor of excessive comments.  I am however saying that
assigning "meaningful" spellings to identifiers can be very tricky.

>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.

Er, this is just plain wrong code.  From Jensen and Wirth, "Pascal User
Manual and Report" 3rd ed. revised by Mickel and Miner, p. 39:  "The
control variable is left undefined upon normal exit from the for
statement."  That means that the variable "I" cannot legally be used as it
is in this example as it is undefined when it is used in the test of the
while statement.  Not all compilers catch this, though it can be done.

>
>(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.

Hear hear!

Try this as a suggested improvement:

const
   mincounter=1;
   stringsize=whatehaveyou;

type
   counterrange=mincounter..stringsize;

var
   r:conterrange;

This allows you to change the counter range by changing only the value of
a constant and buys you the advantages of named types.

A subtle problem occurs when you use type integer willy-nilly when
subranges should be used.  The code for a for statement usually increments
the control variable and then tests to see if the final value has been
exceeded.  If the control variable assumes the value maxint this
incrementation will cause overflow.  So, the compiler must generate extra
code to be sure maxint will not be exceeded prior to the increment and
test step.  That test adds at least two instructions to each pass through
the loop.  If the loop is only executed a few times, it's no big deal, but
if the loop is executed thousands of times (not all that rare in real
programs) then many extra instructions are executed when a little careful
programming would avoid them.

>
>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.

Again, hear, hear.  There is nothing like well written programs.  Well
written programs are (usually) self documenting.  Save comments for those
parts of the code that are difficult to follow because the solution is
inherently difficult to follow.  Remember, bad comments can be just as
misleading as bad code.