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.