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: 1014db,30e368bdb3310fe5 X-Google-Attributes: gid1014db,public X-Google-Thread: 1008e3,30e368bdb3310fe5 X-Google-Attributes: gid1008e3,public X-Google-Thread: 109fba,f292779560fb8442 X-Google-Attributes: gid109fba,public X-Google-Thread: 103376,30e368bdb3310fe5 X-Google-Attributes: gid103376,public X-Google-Thread: f8c65,30e368bdb3310fe5 X-Google-Attributes: gidf8c65,public X-Google-Thread: 10db24,30e368bdb3310fe5 X-Google-Attributes: gid10db24,public From: willer@carolian.com (Steve Willer) Subject: Re: Hungarian notation Date: 1996/05/25 Message-ID: <31a66d08.1045898@sqarc.sq.com> X-Deja-AN: 156644273 sender: news@sq.com (News Administrator) references: <31999F43.41C67EA6@scn.de> <4ns02o$ep3@goanna.cs.rmit.EDU.AU> <4o07o9$rfu@seagoon.newcastle.edu.au> <4o4jeg$7e6@tpd.dsccc.com> organization: Carolian Systems, Toronto ON newsgroups: comp.lang.ada,comp.lang.c++,comp.lang.c,comp.lang.modula3,comp.lang.modula2,comp.edu,comp.lang.eiffel Date: 1996-05-25T00:00:00+00:00 List-Id: kcline@sun132.spd.dsccc.com (Kevin Cline) wrote: >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. This is a very interesting point, and one that my own experience as a former student supports. Although my teachers did require that the code be commented, they never made a reasonable attempt at teaching us what kind of comments should be created, why they're important, caveats, etc. I've had a continuing discussion via e-mail on this topic, and I thought I wrote a reasonably good letter today that perhaps gets into more specifics. I'll reproduce it here: --------------------------------------------------------------------- >Note that everyone agrees that silly comments that just repeat what the >code is doing are useless, but on the other hand, I find the idea of >self-documenting code to be largely bogus. The most code can tell you >is what it does and how it does it (true -- much poorly written code >can't even tell you that). Well, let's say for the sake of argument that it _is_ possible to have fairly good self-documenting code. Would you agree that self-documenting code would be more valuable, from a maintenance perspective, than any comments within the functions? You see, I believe strongly that it _is_ possible to make code clear without resorting to side commentary. So I strive to achieve this whenever possible, and I find that a good notation system helps tremendously. Let me give a quick analogy. If you're watching a movie and you just don't understand what's going on, if you had a choice between someone whispering explanations in your ear and having the movie make sense in the first place, you would probably choose the latter, right? I find that comments sprinkled throughout the code break the "flow" and therefore damage the ability of the maintainer to understand the way the code works without having to mentally step through every line of code. >BUT! it can't tell you the why, and even less the why not (why you did not >do something else). Furthermore, properly written comments are at a level >of abstraction that is definitely above the level of the code, and this >can make it far easier to follow the intent and shape of code without >having to read the code itself (which is at a more detailed level, and >therefore takes more effort to read). Part of the problem is that there are so many different types of comments, it's difficult to have a good discussion about them without recognizing the different types. In particular, there are: 1. design documentation (I consider this to be related to comments) 2. "headers" at the top of functions, indicating what the function does, what the parameters mean, etc. 3. "procedural" comments, which are of the "literate programming" variety, like the example I gave earlier [Note: this point refers to comments that are created to show program structure before the code is written, which is suggested in at least one book that I've read. An example might be: // for every node // tell the node to output its iteration // tell the user that we're done ] 4. "low-level overview" comments, which indicate what is going to be done in a 5-15 line segment. They can also serve to separate a function into multiple higher-level segments. 5. "hack" comments, which document a weird hack or bizarre form of algorithm that you are employing Now, your comment about the useless comments seems to be about the "bad" form of #3. My own personal experience is that I don't get much use out of #3 at all, despite the fact that a number of books seem to recommend this practice. My comment at the top of this letter is in fact about #3 specifically. I personally feel that #1 and #2 are absolutely required for any software that will be maintained by a different person or a few months down the road (i.e. all software). I also feel that #5 is very important, partly so maintainers can understand why the hack was put in, but also perhaps more importantly to be sure that they don't undo the hack (probably every developer has at least once looked in disgust at a hack and "cleaned it up," only to discover later that there was a good reason for it being there). Now, #4, I tend to feel is optional. I try to limit my use of #4 to places where the functions are long or complicated, but since I'm a C++ programmer, one of the design principles I try to live by is "write simple functions". Consequently, #4 isn't needed very much in my code. This is an example where I feel it's much more important to concentrate on design principles than commenting principles. I guess my biggest objection to the "comments are God" type of attitude I see sometimes is that there are more important things to be done, like fixing a bad design. I don't want to see comments being used to cover up a bad design or bad code.