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.