At 3:42 -0500 12/25/97, Gerardo Richarte wrote:
>Hi!
>
>> Kent Beck teaches that a comment is your way of saying that a method isn't
>> done, typically that its name is unclear or that it is poorly written.  In
>> the very successful C3 project, we name our methods to make sense, and we
>> write them to be clear, and we hardly ever need comments.
>
>	It's not allways true, as comments are not here only to help the reader
>understand what's written, but to help the reader understand what the
>writer was thinking when he wrote it...
>
>	Suppose you write some chuck of code to calculate PI, fine, the name of
>the method will be enough to tell me what it's doing, but not to tell me
>why it works that way. May be you need to say something like "for more
>information see Knuth's book" or better you may need to say "For this method
>I have improved an algorithm that works ..." or "While doing this I noticed
>that if I choosed a better first value, by doing blah, I ended faster and
>with a better aproximation" or anithing else...
>	How can you say all this things only with code? do you think it's not
>necesary to say all those things?
>
>	Commenter bye!
>	Richie++

While I fully agree that the code should be as clear as possible (and am
guilty of many sins), I think comments that direct the new reader, specify
WHY something is the way it is, spell out side effects that are obvious to
anyone that knows the code but are not obvious to a new reader (or an old
reader a year later), point to sources for the algorithm, tell why a given
constants is that way or where it came from (as in random number
generators), etc.

But how many times have you read a comment that tells what the code once
did? Comments telling what should be obvious from the code itself should
not be written.

As Einstein once said: Simplify things as much as possible, but not too
much. (And don't forget that he had a wicked sense of humor.)

 Kent is proposing that we should simplify as much as possible; some others
are, IMHO, forgetting the last part and simplifying too much.

Dave

_______________________________
David N. Smith
IBM T J Watson Research Center
Hawthorne, NY
_______________________________
Any opinions or recommendations
herein are those of the author
and not of his employer.