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.