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

[steidl@centuryinter.net]

In <4r1bdp$3ib@nntp.seflin.lib.fl.us>, z007400b@bcfreenet.seflin.lib.fl.us (Ralph Silverman) writes:
>************begin r.s. response*************
>
>	suppose discussion relates to
>		working code
>	yes
>	?

Well, code does not always work, and often comments then become very
useful because they reveal the intent of the author, but assuming
it actually does work...

>	source
>	is determinative of behavior,
>	certainly,
>	in a way comments can not be,
>	yes
>	?

True, but I have yet do have a comment core-dump on me when I wasn't
expecting it ;-)

>	comments can be wrong in a
>                  ^^^^^
>		fundamental way
>	source is not,
>	yes
>	?

Well, given your assumptions, one of which is that the source is
*correct*, I guess the source would not be *incorrect*.

>	on this view comments
>		are less to be trusted!
>	(just add common sense!)

I think of comments as cache and code as main memory (or disk,
depending on how large/old/strange it is).  A good comment is
like a cache hit.  A bad comment is like a cache miss.  You
don't throw out the cache just because it doesn't always hit -
as long as it hits often enough to result in a performance
increase.  The same goes for comments - if the comments for an
entire project are so bad that they waste more time then they
save, then its time to redo them (i.e. fill your cache).
[Note here that comments only perform like a cache if you
correct comments when you find out they are wrong - some
programmers *don't* do this, and unwittingly suffer the
consequences, over and over again.]

>	those who have faith in comments
>	as a shortcut to understanding code
>		are sure to get burned by this
>		^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>	sooner or later...

Getting burned is definitely a page-fault, but you still
don't throw out the cache.

>	the argument here is,  generally,
>	between those who have been burned
>	and those who will be burned!!!

I have been burned in the past,
I am occasionally burned in the present,
I will undoubtedly be burned again in the future.
But I still don't throw out the cache.

Oh, BTW, a folding editor is another way to increase your cache
efficiency.  It would be kind of weird to design a computer that
had to scan through main memory just to access the cache, yet
most editors make you perform a visual scan through the code
just to get to the good-stuff (i.e. the comments).  [OK, so this
analogy is a little weak.  It still gets the point across, I think.]

Oh, and if you really want to have fun, take the first line of the
previous paragraph and use it out of context.

-Jeff