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: f8c65,30e368bdb3310fe5 X-Google-Attributes: gidf8c65,public X-Google-Thread: 1014db,30e368bdb3310fe5 X-Google-Attributes: gid1014db,public X-Google-Thread: fac41,af40e09e753872c X-Google-Attributes: gidfac41,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: dewar@cs.nyu.edu (Robert Dewar) Subject: Re: The Last Word on Comments (was Re: Hungarian notation) Date: 1996/06/12 Message-ID: #1/1 X-Deja-AN: 160290815 references: <4o07o9$rfu@seagoon.newcastle.edu.au> <4o1vo3$p2a@news1.ni.net> <4oegks$ntn@goanna.cs.rmit.EDU.AU> <31BDA39F.14E4@phidani.be> organization: Courant Institute of Mathematical Sciences newsgroups: comp.lang.ada,comp.lang.c++,comp.lang.c,comp.lang.modula3,comp.lang.modula2,comp.edu,comp.lang.eiffel Date: 1996-06-12T00:00:00+00:00 List-Id: 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 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).