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

[steidl@centuryinter.net]

In <4s3397$9ih@nntp.seflin.lib.fl.us>, z007400b@bcfreenet.seflin.lib.fl.us (Ralph Silverman) writes:
>Robert Dewar (dewar@cs.nyu.edu) wrote:
>: "        comments can be wrong in a
>:                         ^^^^^
>:                 fundamental way
>:         source is not,"
>
>: This is wrong. It seems right only if you have no sense of abstraction.
>: The code is *way* over-specified. The function of comments (or one of
>: many functions) is to comment things at the right level of abstraction
>: and at the right level of specification.
>
>: The fact that you have been burned by your own and others inadequate
>: comments inadequately maintained is not a good reason for suggesting
>: that others who are perfectly capable of writing good comments and
>: maintaining them should not do so!
>
>
>--
>************begin r.s. response**************
>
>	if this is restricted to
>		working code
>		^^^^^^^^^^^^
>	then
>		code
>	as distinct from
>		comments,
>	certainly,
>	is
>		authoritative
>	in a way
>		comments can not be!
>
>	that is,  regarding
>		program behavior!!!

And individual molecular movement is more authoritative then a weather
vane regarding air behavior.  But I hardly want to try to examine
individual air molecules just to see which way the wind is blowing!

>	there may be circumstances where
>		this distinction is
>		important
>	yes
>	?

This distinction is very important when the comments say what the
program should do and the code does not correctly implement that.
Oh yes, but you want to ignore this case since it is completely counter
to your argument.  But putting that aside, this distinction is always
important, not just in some circumstances.  The real question is
when should and should not a programmer focus on that distinction.  A
competent programmer will usually know when to focus on that
distinction, and on which side of the fence (if either) to fall.  And
if they make a mistake, they will learn and adapt.  You seem to be
ignoring this critical component altogether.

You also seem to be stating the obvious in hopes that it is going to
somehow lend credence to your argument that there is something
inherently wrong with comments.  Yes, comments are different than code.
Comments only talk about code.  Code *is* code.  An "X Manual" only
talks about "X".  "X" *is* "X".  Maybe we should throw out all manuals?

>	also...
>	regarding
>		'burned'
>	those who assume comments are not
>	at greater liability in this
>	are liable to be mislead by the
>		apparent authority of comments!

Come on.  What "apparent authority of comments"?  Even newbies know
that comments do not affect program behavior.  And even nonprogrammers
know that people can make mistakes and/or be lazy.  So where is this
supposed authority coming from?  Where does it exist?

And I am not at all convinced that "comments are ... at greater
liability in this".  When the program's behavior seems to disagree with
a comment, the comment is easily written-off as probably incorrect.
But when the behavior does not seem to agree with the code,
writing-it-off is not an option.  Time must be spent to understand
exactly why the program is not behaving as expected.  Comments really
only have one way to deceive.  Code can do it in an infinite number of
ways.  Comments are nothing more than free-verse which is, hopefully,
useful more often than not.  On the other hand, code is a reality.
Program behavior is a reality.  When reality does not match reality
it can really play with your mind.  Even though each of these may
only be a perceived reality, perception is the *only* link to reality
we have.  The long, drawn-out mental blocks punctuated by periods of
conceptual slippage and turbulance one goes through in these types of
situations will *never* be matched by a mere comment.  And yes, even
working code can induce this most interesting affect.


-Jeff

steidl@centuryinter.net - http://www.dont.i.wish.com/
All opinions are my own, and are subject to change without notice.