commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gilles Sadowski <>
Subject [Math] Coding and documenting guidelines
Date Tue, 11 Jan 2011 15:15:49 GMT

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.
   * @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,

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message