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: 109fba,f292779560fb8442 X-Google-Attributes: gid109fba,public X-Google-Thread: 10db24,30e368bdb3310fe5 X-Google-Attributes: gid10db24,public X-Google-Thread: 103376,30e368bdb3310fe5 X-Google-Attributes: gid103376,public X-Google-Thread: f8c65,30e368bdb3310fe5 X-Google-Attributes: gidf8c65,public X-Google-Thread: 1014db,30e368bdb3310fe5 X-Google-Attributes: gid1014db,public X-Google-Thread: 1008e3,30e368bdb3310fe5 X-Google-Attributes: gid1008e3,public From: tangent@cyberport.com (Warren Young) Subject: Re: Hungarian notation Date: 1996/05/26 Message-ID: <31a86039.112542988@news.cyberport.com>#1/1 X-Deja-AN: 156716274 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: none newsgroups: comp.lang.ada,comp.lang.c++,comp.lang.c,comp.lang.modula3,comp.lang.modula2,comp.edu,comp.lang.eiffel Date: 1996-05-26T00:00:00+00:00 List-Id: dewar@cs.nyu.edu (Robert Dewar) wrote: > "Comments should be minimized" Just wanted to comment here: I'm all for comments (about 30% of the lines in my recent projects are whitespace or comments), but I do agree with this. I remember seeing one code module that had one comment _per line of code_, and most of the comments were multi-line! There was one section where each line had a six-line or better comment. I think comments force you to give your code a second thought. An old aphorism goes, "The best way to learn something is to try and teach it to someone else," and a comment is your way of teaching future maintenance programmers about your code. I've corrected many potential problems because I did some rethinking after trying to put a comment on it. The main example of this is a bit of code being too complex. If I have to put a 10-line comment on fewer lines of code just to adequately explain it, it's probably too complex, and I end up re-writing it to be clearer. Often, the code is actually more concise and/or smaller/faster as a result. Getting back to that overly-verbose module, I think those comments indicate a programmer that shares my basic views, but didn't actually understand what it was they were writing. In essence, they put every interaction into those comments, stuff that would be a given to someone who knew the underlying subsystems. It'd be like commenting every printf() or cout to take into account what they _might_ do with the data. That's great if the maintenance programmers don't understand these basic facilities, but horrible when they do. I don't know where it was, but I once read of a study that tested code comprehension, plotted against the comment density. It turns out that the optimal density is one comment per four lines of code (I guess 10 comment lines per 40 lines of code would be OK, too) -- any fewer than that caused obvious problems, but any more caused problems too, because the subject had to plow through more verbosity to glean the salient points of the code. And speaking of verbosity, I've said quite enough already. = Warren -- http://www.cyberport.com/~tangent