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: 1014db,30e368bdb3310fe5 X-Google-Attributes: gid1014db,public X-Google-Thread: f8c65,30e368bdb3310fe5 X-Google-Attributes: gidf8c65,public X-Google-Thread: 103376,30e368bdb3310fe5 X-Google-Attributes: gid103376,public X-Google-Thread: 1008e3,30e368bdb3310fe5 X-Google-Attributes: gid1008e3,public X-Google-Thread: 10db24,30e368bdb3310fe5 X-Google-Attributes: gid10db24,public From: jcm@hgc.edu (James McKim) Subject: Re: The Last Word on Comments (was Re: Hungarian notation) Date: 1996/06/17 Message-ID: <1996Jun17.155645.28063@merlin.hgc.edu>#1/1 X-Deja-AN: 160672079 sender: usenet@merlin.hgc.edu (Action News Central) references: <31BDA39F.14E4@phidani.be> organization: The Hartford Graduate Center newsgroups: comp.lang.ada,comp.lang.c++,comp.lang.c,comp.lang.modula3,comp.lang.modula2,comp.edu,comp.lang.eiffel Date: 1996-06-17T00:00:00+00:00 List-Id: In article dewar@cs.nyu.edu (Robert Dewar) writes: >Darius said > >"Please excuse me for not feeling concerned about the 'ignorant' adjective, >but I kind of disagree with you here. We try to promote an approach where >comments should be formal as far as possible, hence, executable. Assertions >(pre and post-conditions, etc...) are often understood as a quality insurance >feature, while we consider it as a way for the code to express the implicit >knowledge he (or she) has about how things are supposed to happen in >a formal, standardized, and executable way." > >This seems quite bogus to me. The only kind of comments that can be >formalized this way are rather trivial ones that say what the code does, >and the danger of trying to formalize even these is that you end up >overspecifying and cannot describe things at the right level of Based on previous posts of yours I suspect you didn't think this one all the way through. Comments that describe what the code does without giving away how it does it are hardly trivial or bogus. In fact these are the basis for information hiding and specified public interfaces of classes. You _must_ provide these kinds of comments if you expect people to use your class correctly without actually looking at your code. Overspecifying (and underspecifying for that matter) is a danger whether the comments are compilable or not. OTOH, one of the many advantages of compilable specifications is that it is often trivial to discover when a change in the code has introduced an error wrt the spec. >abstraction. For example, a comment that says > > "Give the error message now, in case later processing bombs, to be sure > that the error message will be seen" > >is not easily formalized. Actually this comment has two parts. The first >is the "what" [give error message now) and that is rather trivial, it may >help by abstracting what is there but it still is nly saying what the code >is doing. The rest of the comment is the WHY > >The WHY is a critical part of comments, and good WHY comments are what to >me distiguishes good code. To the extent that the no-comment or lo-comment >school wants to eliminate WHY comments, they are damaging code quality in >my opinion. > >Even more subtle, and difficult to formalize, but often crucial is he >the WHY NOT comment (why you didn' >t do something). I agree that the above are important and are not easily formalized and I didn't catch the original article, but I doubt that Darius was arguing that compilable pre/postconditions be the _only_ form of documentation. I think you (Robert) are concentrating too much on documentation that is useful only to the implementors, present and future, of the software. Rigorous assertions are useful to both implementors _and clients_ of a class. Continuing to think as a client, in addition to the above I would want documentation showing me sample uses of the class in question, yet another form that would be difficult to formalize. Hope this helps, -- Jim > -- *------------------------------------------------------------------------------* Jim McKim (860)-548-2458 Co-editor of Eiffel Outlook Internet: jcm@hgc.edu Subscribe early and often!