>I don't know. I would like to see an example of what you consider a
>useful comment within the code.
OK, I guess you're really serious about all comments being useless.
Example 1:
/* keep the table size a prime number if you grow it -- modulus
* is a significantly better hash function if the denominator is prime.
*/
TObject* HashTable[31];
Programmers *cannot* intuit from the code that modulus is a better
hash function when the denominator is prime. Sorry, they just can't.
Either they know it or they don't. The author can either leave those
that don't happen to know this fact clueless (in which case they are
liable to needlessly degrade the design during maintenance), or
can simply include a comment. Even if you document this fact in
a design document, the odds are fair that the guy getting ready to
change that table size didn't read it or doesn't remember it. This is
a case where you want that information RIGHT THERE with the
code to prevent damage during maintenance. That's what a comment
is for.
Example 2:
/* Work around a bug in early versions of Windows' comctl32.dll
*/
if(ListView.item.rc.ul < 0)
ListView.item.rc.ul = 0;
This is representative of a whole class of comments of the form:
"I know you don't see any need for this code, so I will tell you
why it exists." Without this sort of comment, extreme amounts of
time and money are wasted as a maintenance programmer
"refactors" out some "unnecessary" code, ships a product, and
much later discovers that in some very obscure situation, that
code really, really was needed. Can you intuit that need from
the code? Absolutely not! Is there some superior way to convey
that information instead of a comment? I don't think so -- you want
that information Right There so that the programmer who would
likely do the damage can't miss it.
Example 3:
/* Use the algorithm from Foley and Van Dam, p. 254, 2nd edition.
*/
Many programmers go for great lengths of time without seeing any
code that is particularly tricky or complex. However, that doesn't mean
that's how the whole world of programming is. There are situations
that call for algorithms that are simply hard to get right (as the recent
posting about translating between different color spaces shows). Most
especially in the (rather large) realm of graphics programming,
citing the source of your algorithm can be invaluable to maintenance
programmers who are trying to figure out if that code is the source
of a bug or not. Otherwise, they are liable to a) replace it with
home-grown slop that has many more problems or b) replace it
with an inferior published algorithm because they were unaware of
the source of yours. It is Extremely Painful to reverse engineer from
the code the fact that a particular complex algorithm is being used,
and they certainly arise in all manner of situations, from graphics,
to database structures, to even financial algorithms (a friend of mine
recently had to interface to several banks, and found that they each
had unique errors in how they calculated their mortgage interest --
none of them agreed, so he was certain that most banks were wrong,
even if his code was in error :-).
-----------------------
Had I more time, I would be happy to emit endless examples of very
useful comments! :-)
- Automatic footer for [EMAIL PROTECTED] ----------------------------------
To unsubscribe from this list, mail [EMAIL PROTECTED] unsubscribe discuss
To join the announcements list, mail [EMAIL PROTECTED] subscribe announce
To receive a help file, mail [EMAIL PROTECTED] help
This list is archived at http://www.mail-archive.com/discuss%40ppig.org/
If you have any problems or questions, please mail [EMAIL PROTECTED]
