commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ted Dunning <ted.dunn...@gmail.com>
Subject Re: [Math] Coding and documenting guidelines
Date Tue, 11 Jan 2011 16:38:54 GMT
On Tue, Jan 11, 2011 at 7:38 AM, sebb <sebbaz@gmail.com> wrote:

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

See
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide

<http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide>Note
that several items there conflict with what Gilles suggested.


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

Certainly all checked exceptions.  Unchecked exceptions are a bit more hazy.
 Should all code that has any arithmetic or pointer dereferencing document
the related exceptions?  Probably not.  Clarity can be compromised by too
much goo just as much as with too little.



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

Also -1  for exactly the reasons stated.



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

-1.  Specifically the style standards suggest that sentence fragments
*should* be used in some cases.


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

Again, this is in direct contradiction with the style standards.



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

These are all good if downgraded to a very strongly emphasized should
instead of must.

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message