commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebb <seb...@gmail.com>
Subject Re: [Math] Coding and documenting guidelines
Date Tue, 11 Jan 2011 15:38:10 GMT
On 11 January 2011 15:15, Gilles Sadowski <gilles@harfang.homelinux.org> wrote:
> Hi.
>
> Is there a document presenting best practices for writing code for CM?

Sun/Oracle have Javadoc conventions which should be followed.

> 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)

+1

> * The "@param" tag should not contain redundant information (such as
>  preconditions since they must be documented in a "@throws" tag).

-1

It's a lot easier to read the preconditions in the param description,
rather than wading through all the throws descriptions to see if the
parameter is mentioned.

But where there are only one or two params and throws the duplication
may be unnecessary.

> * 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".
>   */

I think the Javadoc standards may have useful guidance here too.

> * 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.
>   */

+0 - does not seem like a big deal.

> * 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

+1

>  <code>...</code> constructs.

AIUI <code> is obsolete.

> * etc.

The class Javadoc needs to mention thread-safety (or otherwise).

If user code needs to apply synch. to ensure thread-safety, then the
Javadoc should say what lock(s) need to be held.

@since tags must be used where relevant
@deprecated/@Deprecated tags/annotations should say when the item was
deprecated, and when it is due to be removed (if known)

@SuppressWarnings should be applied as close as possible to the code
that causes the warning (this may involve creating a temporary
variable) and should have a comment that explains why the warning is
safe to ignore.

>
> 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: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message