On Sun, Mar 16, 2008 at 03:52:52PM -0700, Andrew Lentvorski wrote:
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.
I would argue that separate documentation is a bad idea, at least for a
functional interface. Take 'C' for example. The documentation for the
interface should be in the public header file for the library. The best
examples of this I know of are zlib.h and sqlite3.h. Neither of these
requires external documentation to be able to work with the library. Most
other libraries I interface with involve trudging through crappy web
interfaces only to find documentation that is out of date with the code.
The further it is away from the code, the less likely it is to be correct.
Sitting in a plain text file next to the source is a little bit better. Of
in some alien documentation format makes it less likely to be available.
Trying to program windows has been one of the most unpleasant things I've
ever tried doing, largely because of this.
A lot of modern languages are getting pretty good about solving both of
these problems. The code stays as the definitive description, and the
documentation is generated from the code.
- 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.
Huh? I've given two examples to the contrary. My last project at work is
another example. Clients of our software would start by asking where the
interfaace documentation was. I would point them to the well-written
header file. They then are quite happy to figure out that they already
have everything they need to know.
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.
Then I must not have been very clear. The comment should never explain
what is obvious to a knowledgeable user of the language. There is a
difference between explaining the obvious. It's this kind of thing I'm
referring to:
/* FUNCTION blort
*
* arg1 - An integer argument.
* arg2 - A string argument.
* returns an integer
*/
int blort (int arg1, char *arg2);
The best indicator of what the argument is for would be it's name. A
comment should not explain that it is an integer, but what is its meaning.
Is it a count of something, or an index, or something else.
The comment should certainly be used when something unusual is happening.
I would defintely agree that:
c = x & -x;
needs a comment.
David
--
[email protected]
http://www.kernel-panic.org/cgi-bin/mailman/listinfo/kplug-lpsg
