commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gilles Sadowski <gil...@harfang.homelinux.org>
Subject [Math] Coding and documenting guidelines
Date Tue, 11 Jan 2011 15:15:49 GMT
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: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message