Path: utzoo!utgpu!water!watmath!clyde!att!rutgers!ucsd!ames!amdcad!sun!pitstop!sundc!seismo!uunet!mcvax!dkuug!freja!stuf
From: stuf@freja.dk (Kristoffer H. Holm)
Newsgroups: comp.lang.pascal
Subject: Re: Re: Comment Pollution
Message-ID: <3987@freja.dk>
Date: 19 Aug 88 15:30:16 GMT
References: <6508@uwmcsd1.UUCP> <840@buengc.BU.EDU>
Organization: DIKU, U of Copenhagen, DK
Lines: 63

In article <840@buengc.BU.EDU> art@buengc.BU.EDU (A. R. Thompson) writes:
>...
>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.

Why, it should have been named tty_not_in_use (or TtyNotInUse if you prefer
that)!  In my opinion, properly written Pascal programs only need 
intensional comments, stating the purpose of chunks of code -- the primary
purpose of comments is to allow the reader/maintenance programmer to SKIP
code that is irrelevant to him/her!  In the example a comment would have
done no good (especially not a misleading one)!

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

Right. While we're at it: variables used as counters in for loops must
also be local to the enclosing  (program/procedure/function body)
of the loop, making "{loop variable in procedure xxxx}" comments dubious.

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

In general I don't agree: you use the wrong principle.  Constants and
Types shall only be named if they can be misunderstood, or are used in
more than one place.  And it is OK to have the constants 0 and 1 in ranges.
Otherwise you commit a sin similar to over-commenting, and use to many
different names. In the above example,

	type	string_index = 1..whatever;
	var	r: stringindex;

is more readable---note that "string_index" is a better type name than
"counterrange": it shows the intension of the type, not its applications!
Of course, "r" should be called something else (not apparent from the
example).

Regards, Kristoffer.

---------------------------------------------------------------------------
Kristoffer H. Holm					eunet: stuf@diku.dk
Institute of Datalogy (1. sal N), Univ. of Copenhagen,
DK-2100 Copenhagen East, DENMARK
---------------------------------------------------------------------------