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: 1014db,30e368bdb3310fe5 X-Google-Attributes: gid1014db,public X-Google-Thread: f8c65,30e368bdb3310fe5 X-Google-Attributes: gidf8c65,public X-Google-Thread: 10db24,30e368bdb3310fe5 X-Google-Attributes: gid10db24,public X-Google-Thread: 103376,30e368bdb3310fe5 X-Google-Attributes: gid103376,public X-Google-Thread: 1008e3,30e368bdb3310fe5 X-Google-Attributes: gid1008e3,public From: zink@panix.com (David Zink) Subject: Re: The Last Word on Comments (was Re: Hungarian notation) Date: 1996/06/18 Message-ID: <4q79lr$ju5@panix3.panix.com>#1/1 X-Deja-AN: 160903926 references: <31bf6e29.185297643@netline-fddi.jpl.nasa.gov> <31C685A1.F1@wgs.estec.esa.nl> organization: Panix Public Access Internet & Unix, NYC newsgroups: comp.lang.ada,comp.lang.c++,comp.lang.c,comp.lang.modula3,comp.lang.modula2,comp.edu,comp.lang.eiffel Date: 1996-06-18T00:00:00+00:00 List-Id: In article <31C685A1.F1@wgs.estec.esa.nl> Sandy McPherson writes: >C is not by definition a write only language. The problem is that there >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 Your two examples illustrate your confusion. > > /* 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. Somewhere there is a person so unfamiliar with typical programming and mathematical symbology that the comments on your first example would be necessary in order for them to understand the behavior of the procedure. An Ada programmer has no business maintaining a C program. A program may be documented in an instructional manner, so that it is appropriate reading for a non-programmer, but it is hilarious (i.e. likely) to suggest that the manpower be invested so that all the code in all applications be suitable as instructional material. In fact, in a delivered application, commentary performs only a few possible functions. It may be used to document the sources of algorithms, this is entirely appropriate, since otherwise they are essentially pirated. It may be referenced when the code is reviewed, or needs to be "improved", which are essentially the same as the following cases: It may be referenced when the code has failed in the field and needs to be maintained, in which case it may be a comment of the form "this code will fail under the following circumstances"; such comments should be excised and replaced with thrown exceptions appropriate to the particular language. Or it may be any other sort of comment: such comments should be excised since they falsely document the program to work correctly. I left out the sort of comment that attempts to document the manner in which some obscure piece of "beautiful" hackwork implements some simple function in a particularly "efficient" manner. But that's alright, they almost always fall under the final category of comments listed above. My feeling after years of programming is that the only meaningful documentation a procedure carries are the documentation of its interface and its evolution, and the code itself. Any comment inserted in the code is a mistake for which someone will eventually pay. --David Occasionally we will get a customer error report wich claims that our program dumped core because an assertion failed. The chief programmer's response is almost invariably simply to remove the assertion, thus eliminating the core-dump. Sometimes he goes through the code and removes all assertions, simply as a prophylactic.