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++
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.
<x-rich>
As Einstein once said: Simplify things as much as possible, but not
too
much.
Urf. I believe that was "Make things as simple as possible, but no simpler." Half the fun of quotes is the delivery. :)
As Graham Chapman once said, whilst impersonating Oscar Wilde (or was it George Bernard Shaw? :), "I wish <italic>I</italic> had said that."
-C
--
Craig Latta
composer and computer scientist
craig.latta@netjam.org
www.netjam.org
latta@interval.com
Smalltalkers do: [:it | All with: Class, (And love: it)]
</x-rich>
<x-rich>At 22:17 -0500 12/28/97, Craig Latta wrote:
<excerpt> > As Einstein once said: Simplify things as much as possible, but not too
much.
Urf. I believe that was "Make things as simple as possible, but no simpler." Half the fun of quotes is the delivery. :)
As Graham Chapman once said, whilst impersonating Oscar Wilde (or was it George Bernard Shaw? :), "I wish <italic>I</italic> had said that."
</excerpt>
Craig:
That's what I get for trying to quote from a leaky memory. Thanks.
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.
</x-rich>
squeak-dev@lists.squeakfoundation.org