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=0.2 required=5.0 tests=BAYES_00,INVALID_MSGID, REPLYTO_WITHOUT_TO_CC 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: 1014db,30e368bdb3310fe5 X-Google-Attributes: gid1014db,public X-Google-Thread: f8c65,30e368bdb3310fe5 X-Google-Attributes: gidf8c65,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: 1008e3,30e368bdb3310fe5 X-Google-Attributes: gid1008e3,public From: ian@rsd.bel.alcatel.be (Ian Ward) Subject: Re: The Last Word on Comments (was Re: Hun Date: 1996/06/20 Message-ID: <4qbfg2$m8u@btmpjg.god.bel.alcatel.be>#1/1 X-Deja-AN: 161193374 distribution: world references: <31C685A1.F1@wgs.estec.esa.nl> organization: Alcatel Bell Telephone reply-to: ian@rsd.bel.alcatel.be newsgroups: comp.lang.ada,comp.lang.c++,comp.lang.c,comp.lang.modula3,comp.lang.modula2,comp.edu,comp.lang.eiffel Date: 1996-06-20T00:00:00+00:00 List-Id: In article F1@wgs.estec.esa.nl, Sandy McPherson () writes: >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 True, but neither is terseness comprehension; nor is verbosity incomprehension I think it would be fair to say that, in general, terseness causes more problems than it solves, it is probably true to say that terseness causes more incomprehension than does verbosity; and comprehension is achieved much faster in the presence of description, than in the absence of description. After all, like the compiler, one can always ignore well written comments if they are there. One cannot, however, take them into account if they lack existence. > >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*/ > ; I do not understand this drivel WITH the comments, just exactly what does it do? Is it a test to discover which level of optimisation removes empty loops, or is it part of a performance test for the system? Perhaps it is just a non portable delay? Some descriptive comments would help. The comments do imply that the loop is semantically the same as an Ada while loop as opposed to an Ada for loop, which is of some help (at least it would be in the real world case when the loop had contents and the tester was trying to track down an infinite loop problem.) >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. Well in the event of the code not working for some reason, such as a compiler fault, it would tell the maintainer of the code what the code was actually meant to do. This will obviate his search through all the calling procedures, to see how they work, to deduce the reasons and circumstances behind the faulty procedure call. Now, I agree that in your two simple contrived examples, standalone, comments are less likely to be helpful, than in the real world case, where there are twelve million lines of code and the people who wrote the piece that has been discovered to be faulty, left two years ago. > But if a QA guy who is >by nature an Ada programmer were to read this he would probably need >the comments. > All the "by nature" Ada programmers I know can write 'C', if need arises. Best regards, Ian --- Ian Ward's opinions only : ian@rsd.bel.alcatel.be