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

[dewar@cs.nyu.edu (Robert Dewar)]

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).