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: 109fba,f292779560fb8442 X-Google-Attributes: gid109fba,public X-Google-Thread: fac41,af40e09e753872c X-Google-Attributes: gidfac41,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: 10db24,30e368bdb3310fe5 X-Google-Attributes: gid10db24,public X-Google-Thread: 1008e3,30e368bdb3310fe5 X-Google-Attributes: gid1008e3,public From: willer@carolian.com (Steve Willer) Subject: Re: Hungarian notation Date: 1996/05/23 Message-ID: <31a4f8b5.80438504@sqarc.sq.com>#1/1 X-Deja-AN: 156419723 sender: news@sq.com (News Administrator) 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: 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-23T00:00:00+00:00 List-Id: dewar@cs.nyu.edu (Robert Dewar) wrote: >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. As with everything, comments can hurt or they can help. If you require the developer to sprinkle comments all over their code, they will almost certainly get out of date. I prefer to concentrate on writing code that's as clear and self-documenting as possible, inserting comments in places where it is necessary to give the "big picture" of what I'm doing. I've found it counterproductive to create comments like this, for example: Bar(vector &vFoo) { // for each Foo... for_iter(vFoo, FooIterator) { // run some calculations on it DoSomeStuff(*iter); } } (Please excuse my for_iter macro; I'm very proud of my new creation and I like to use it whenever possible) The above code is an example of the "write comments that indicate the structure of your code" form of commenting that I played around with for a while. I found it unwieldy. I also decided that if your code is so complicated that you have to comment _every step_, then you need to rethink your design. But as I noted earlier, there are times when comments are very good for giving context to an unfortunate hack you had to pull together, or a particularly complicated algorithm. I tend to write those in "essay" style, sometimes making them 5-9 lines of comments. I also write up comments to subdivide logical sections of medium-length functions (I completely disallow longer functions)...perhaps something like: bool Go() { // initialize the internal View ... // generate the output ... // cleanup ... } ...but that's as far as I go. Is that less than what you like, or is it what you're talking about? >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. I wish teachers would also stress the need for writing code that's as self-documenting as possible. If it's possible to make code very clear without comments, I feel that's much more valuable than adding 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. Lots of those. :-) >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. Part of the reason I try to keep it at a minimum.