Re: The Last Word on Comments (was Re: Hungarian notation)

[jcm@hgc.edu (James McKim)]

In article <dewar.834584583@schonberg> 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!