Hi.
Is there a document presenting best practices for writing code for CM?
Right now I'm thinking about the recent overwrites of Javadoc comments; so I
think that it could be useful to lay out what should be there (beyond the
obvious that "everything should be documented").
A few things that come to mind:
* All exceptions that could be thrown must be documented in a "@throws" tag,
indicating all the possible causes of the exception (such as the
assumed preconditions)
* The "@param" tag should not contain redundant information (such as
preconditions since they must be documented in a "@throws" tag).
* Javadoc comments must be composed of full sentences (except for the
definition of a "@param"), including punctuation and uppercase at the
start of the sentence. E.g. write
/**
* @param x Value of the parameter. A value of -1 indicates that
* the parameter is not used.
*/
but not
/**
* @param x Value of the parameter. -1 for "not used".
*/
* The comment for a "@param" tag should not start with the word "the". E.g.
do not write:
/**
* @param x The value of the parameter.
*/
* In a "@param" description, do not repeat the name of the parameter. E.g.
do not write
/**
* @param x Value of the "x" parameter.
*/
* When a description starts with a verb, write it in the imperative form
(not the at the third person of the present tense). E.g. write
/**
* Compute the value of the function.
*/
rather than
/**
* Computes the value of the function.
*/
* The comment of a "@return" tag must be the sentence part that completes
the expression "This method returns ...". E.g.
/**
* @return the value of the function.
*/
or
/**
* @return a random value between 0 and 1.
*/
* Do not specify the type of the returned value. E.g. do not write:
/**
* @return a random double value between 0 and 1.
*/
* Avoid starting the description of a method with "This method".
* In Javadoc comments, expressions that include code statements must be
written inside {...@code ...} constructs.
* Simple mathematical formulae must be included in {...@code ...} or
<code>...</code> constructs.
* etc.
I think that complying with such rules will ensure completeness and clarity
without the overload of redundant information, and will go some way towards
uniformization of the documentation.
Best regards,
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
