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.9 required=5.0 tests=BAYES_00 autolearn=ham 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: 109fba,f292779560fb8442 X-Google-Attributes: gid109fba,public X-Google-Thread: 10db24,30e368bdb3310fe5 X-Google-Attributes: gid10db24,public X-Google-Thread: f8c65,30e368bdb3310fe5 X-Google-Attributes: gidf8c65,public X-Google-Thread: 1014db,30e368bdb3310fe5 X-Google-Attributes: gid1014db,public X-Google-Thread: 103376,30e368bdb3310fe5 X-Google-Attributes: gid103376,public X-Google-Thread: 1008e3,30e368bdb3310fe5 X-Google-Attributes: gid1008e3,public From: kcline@sun132.spd.dsccc.com (Kevin Cline) Subject: Re: Hungarian notation Date: 1996/05/24 Message-ID: <4o4jeg$7e6@tpd.dsccc.com> X-Deja-AN: 156548842 references: <31999F43.41C67EA6@scn.de> <4ns02o$ep3@goanna.cs.rmit.EDU.AU> <4o07o9$rfu@seagoon.newcastle.edu.au> organization: DSC Communications Corporation Switch Products Division newsgroups: comp.lang.ada,comp.lang.c++,comp.lang.c,comp.lang.modula3,comp.lang.modula2,comp.edu,comp.lang.eiffel Date: 1996-05-24T00:00:00+00:00 List-Id: In article , Robert Dewar wrote: >.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". How much time do you spend showing your students how to write useful comments, or demonstrating good coding style? Is Kernighan & Plaugher's "The Elements of Programming Style" a required or suggested text at NYU? This is a subject that seems to be largely ignored in undergraduate curricula. The developers that do know how to comment seem to have learned by example. >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. Comments should rarely require maintainence. Largely they should be limited to describing a class and it's relationship to other classes, or describing the inputs, outputs, preconditions and postconditions for an entire method. Few methods should be so complex that they require additional comments describing the method implementation. >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. I really liked this section. I thought it was very important to counter the typical methodologies of 2167A DoD software projects, which had a tendency to have rules like "one comment for every five lines of code". Maybe Mr. Dewar has been fortunate enough to have never worked on a software developed using DoD 2167A methodology. >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. Most teachers tell students to comment. Few seem interested in telling students how to write useful 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. Agreed!! But these comments seldom require maintainence. Most maintainence involves either fixing bugs in old code, or adding new features to old code, presumably by adding new methods. These activities should seldom require changing existing comments. Less frequently, implementation decisions will change, and these changes should be documented. >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! That's good. Presumably you are giving them feedback on their commenting and coding style as well. Your students should be well-prepared. -- Kevin Cline