From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me X-Spam-Level: X-Spam-Status: No, score=-1.3 required=5.0 tests=BAYES_00,INVALID_MSGID autolearn=no autolearn_force=no version=3.4.4 X-Google-Language: ENGLISH,ASCII-7-bit X-Google-Thread: fac41,af40e09e753872c X-Google-Attributes: gidfac41,public X-Google-Thread: 10db24,30e368bdb3310fe5 X-Google-Attributes: gid10db24,public X-Google-Thread: f8c65,30e368bdb3310fe5 X-Google-Attributes: gidf8c65,public X-Google-Thread: 109fba,f292779560fb8442 X-Google-Attributes: gid109fba,public X-Google-Thread: 103376,30e368bdb3310fe5 X-Google-Attributes: gid103376,public X-Google-Thread: 1014db,30e368bdb3310fe5 X-Google-Attributes: gid1014db,public X-Google-Thread: 1008e3,30e368bdb3310fe5 X-Google-Attributes: gid1008e3,public From: dewar@cs.nyu.edu (Robert Dewar) Subject: Re: Hungarian notation Date: 1996/05/23 Message-ID: #1/1 X-Deja-AN: 156372447 references: <31999F43.41C67EA6@scn.de> <319D2278.3F9A@netonecom.net> <4nr50r$jo2@ringer.cs.utsa.edu> <4ns02o$ep3@goanna.cs.rmit.EDU.AU> <4o07o9$rfu@seagoon.newcastle.edu.au> organization: Courant Institute of Mathematical Sciences newsgroups: comp.lang.ada,comp.lang.c++,comp.lang.c,comp.lang.modula3,comp.lang.modula2,comp.edu,comp.lang.eiffel Date: 1996-05-23T00:00:00+00:00 List-Id: Peter Moylan wrote: .Richard A. O'Keefe (ok@goanna.cs.rmit.EDU.AU) wrote: .>nreitzel@lonestar.jpl.utsa.edu (Norman L. Reitzel ) writes: .>>As for serious code, I've ported million line projects for a telephone .>>company, and managed projects that produced twice that. The key to .>>maintainability is defensive programming, and ADEQUATE BLOCK COMMENTS. .>>Any chunk of code that does not contain info about what it does and how .>>it does it is an error waiting to happen. The rude concept of .>>"self-documenting" code belongs in an ivory tower with those who teach, .>>not in the trenches with those of us who DO. . .>Those of us who teach struggle hard to persuade students to write .>good comments. . .I don't know where this myth comes from. In my 20+ years in .academia, I have NEVER met a software teacher who considered .uncommented code to be acceptable. Practically everyone tries .to get across the message "write the comments first, and then .the code". In fact the anti-comment attitude comes from the trenches rather than from the ivory tower. The main argument seems to be that since no one can ever manage to maintain comments properly, it is better to have no comments, or at least to minimize comments. I strongly disagree, and feel that it is better still to keep the comments up to date. A bad comment is a bug, as serious as any other latent bug in the "real" code, and programmers have to start thinking that way. Yes of course it is hard to keep comments up to date -- there are many hard things about programming, this is one of them. To see the anti-comment view, look at section 3.3 of AQ&S (one of the few sections of this document that I am not fond of). It starts by saying "Comments in source text are a controversial issue" (!) and then goes on to present what supposedly is a balanced discussion on this issue that to my taste is far too anti-comment. Some excerpts: "There are argments both for and against the view that comments enhance readability" "Comments should be minimized" "source text should .. so that little additional commentary is needed" There is nothing exactly *wrong* with any of these statements, but the general tone adds up to me to be far too anti-comment. As Peter says, most teachers stress comments. I certainly give zero to any assignment that is uncommented, and take marks off for incompetent, incorrect or annoyingly useless ("increment I") comments. In practice many programmers are incapable of writing coherent English, so they have no chance in any case of writing useful comments, and many other programmers are lazy and don't feel like commenting code. Maintenance programmers are often still more lazy and try to change the minimum number of characters to make a problem go away, and of course this does not include changing comments. To me good comments are essential, the code can only tell you what it does and how at a level of abstraction matching the code. Good comments tell you: a) what the code is doing at a higher level of abstraction b) why you did what you did c) why you didn't do something else obviously code cannot be self-documenting in these three aspects. Of course I agree that incorrect or inconsistent or out-of-date comments are a menace, but that's an argument for making sure the comments are correct, consistent and up-to-date, not for eliminating them! Incidentally, I also follow Peter's rule of never helping with uncommented code, and in fact if students show me uncommented code, I take marks off the assignment no matter WHAT is eventually handed in, since I insist that coments must be written as part of the process of coding, not as an after-thought. In practice, this works very well, since I use email to give continuous feedback to students on early versions of their assignments, and they find this feedback valuable enough to be worth the nuisance of commenting their code!