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: f8c65,30e368bdb3310fe5 X-Google-Attributes: gidf8c65,public X-Google-Thread: 1014db,30e368bdb3310fe5 X-Google-Attributes: gid1014db,public X-Google-Thread: 10db24,30e368bdb3310fe5 X-Google-Attributes: gid10db24,public X-Google-Thread: 1008e3,30e368bdb3310fe5 X-Google-Attributes: gid1008e3,public X-Google-Thread: 103376,30e368bdb3310fe5 X-Google-Attributes: gid103376,public From: Sandy McPherson Subject: Re: The Last Word on Comments (was Re: Hungarian notation) Date: 1996/06/18 Message-ID: <31C685A1.F1@wgs.estec.esa.nl>#1/1 X-Deja-AN: 160843241 references: <4o07o9$rfu@seagoon.newcastle.edu.au> <4o1vo3$p2a@news1.ni.net> <4oegks$ntn@goanna.cs.rmit.EDU.AU> <31bf6e29.185297643@netline-fddi.jpl.nasa.gov> content-type: text/plain; charset=us-ascii organization: European Space Agency mime-version: 1.0 newsgroups: comp.lang.ada,comp.lang.c++,comp.lang.c,comp.lang.modula3,comp.lang.modula2,comp.edu,comp.lang.eiffel x-mailer: Mozilla 3.0b4Gold (X11; I; SunOS 5.4 sun4) Date: 1996-06-18T00:00:00+00:00 List-Id: C is not by definition a write only language. The problem is that there are too many write only C programmers. tersity != incomprehensibility verbosity != comprehensibility I have seen code with no comments which you would have to be a raving moron not to understand and on the other hand lots of verbose drivvle like int i; /* loop counter * / for ( i =0; i < maximum; i++ ) /* loop while i < maximum*/ ; also, confusion exists between "readable to a C programmer" and readable to a layman, or an Ada programmer for that matter e.g:. /* open the file called file_name */ fd = fopen( file_name, "w" ); /* check if the file was opened correctly */ if ( fd == NULL ) /* tell the user what went wrong opening file_name by writing a diagnostic to the error stream */ (void)fprintf( stderr, "Error opening %s:\n%s\n", file_name, strerror( errno ) ); else { /* do something useful */ } What value do the comments have for an experienced C programmer? None I would suggest, not even for maintainability. But if a QA guy who is by nature an Ada programmer were to read this he would probably need the comments. Comments are for increasing clarity, use them to explain what is not obvious from your code and to document the reasons why the code looks like it does (i.e. references to requirements, interface control, etc.) For instance a function implementing a Simpson's rule should have a comment like /* Simpson's Rule, see "My Favaourite Algorithms page 21" */ and if you program it neatly and readably no other comment should really be necessary. Let typists type and progarammers program. I can touch type, but I cannot program or write letters at touch typing speeds, as for both exercises I need to have more then my eyes and fingertips engaged. -- Sandy McPherson MBCS CEng. tel: +31 71 565 4288 (w) ESTEC/WAS +31 527 68 1314 (h) P.O. Box 299 NL-2200AG Noordwijk