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 );
--
Where did Gosling get the idea for Javadoc from? Maybe someone he met?
Stewart Stremler
--
[email protected]
http://www.kernel-panic.org/cgi-bin/mailman/listinfo/kplug-lpsg
