David Brown wrote:
- One comment should be for the person who wants to use the function.
The should not care how it is implemented, but what it does and how
they should be using it.
This is called *documentation*, and that's where it should stay.
- The other comment, which should be near the function, should be written
for someone who wants to understand the implementation or modify it.
It should be assumed this person is fluent in the language, and should
describe the stuff that isn't obvious.
This is the *only* comment that should ever exist. No one is going to
read the first type anyhow.
A good rule is that a comment should never describe anything that is
specified in the code. The programming language is a more exact way of
describing these things.
Wrong. A comment should appear the moment something unusual is
happening. I can specify an algorithm *very* precisely in a programming
language, but it would be completely impeentrable. For example, bit
counting tricks are fairly standard in come arenas, but you would never
figure out the algorithm without an plain language reference.
With code that is maintained by a team of engineers, comments as to
who changed what, when, and why are necessary, and in most cases,
mandatory. Often a simple changelog at the top of the file is not
enough to adequately explain the changes made.
Or, get a [EMAIL PROTECTED] revision control system. Any comment, anywhere,
that
describes a change or it's purpose tells me that the revision control
system is broken.
Agree wholeheartedly.
-a
--
[email protected]
http://www.kernel-panic.org/cgi-bin/mailman/listinfo/kplug-lpsg
