SJS wrote:
begin quoting David Brown as of Sun, Mar 16, 2008 at 04:38:35PM -0700:
[snip]
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.
Anything that you'd have to puzzle out after six months or more away
from the code should probably include a comment.
And for comments, why is better than what.
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.
/* blort
*
* This function blortifies the specified string (in-place) and
* answers the number of changes made, or answers a negative value
* if the string is malformed (or some other error occurs).
*
* arg1 - A non-negative integer value indicating the degree of
* desired transformation. Note that prime values are
* isomorphic transformations.
* arg2 - A non-null modifiable blortifiable string.
* returns negative values on error, otherwise the number of changes made.
*/
int blort( int arg1, char *arg2 );
And I would hurt you both right off the bat for arg1, arg2.
Those better be something like:
(int transformLevel, char* blortString)
Unfortunately, this is a *classic* C failure mode. Since nobody has an
editor that does autocomplete in C, everybody writes cryptic variable
names.
-a
--
[email protected]
http://www.kernel-panic.org/cgi-bin/mailman/listinfo/kplug-lpsg
