commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gilles Sadowski <gil...@harfang.homelinux.org>
Subject Re: [Math] Coding and documenting guidelines
Date Wed, 12 Jan 2011 22:32:29 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").
> 
> Yes.  See http://commons.apache.org/math/developers.html.
> >
> > 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 - tricky to do in all cases since we have abandoned checked
> exceptions and unchecked exceptions can propagate unexpectedly through
> API layers.  I do agree with the spirit of this, though and would say
> *must* for exceptions that may immediately be thrown as a result of
> precondition violation.  This follows from the principles laid out in
> the Developer's Guide.

This is not difficult if done immediately by the person who writes the
original code; he knows which calls his code makes and what exceptions can
be triggered, so he reports them in doc.  Of course, for someone that come
afterwards this is much more difficult as he will have to read through the
whole code and track all the calls...
That's why the "guidelines" should insist that we don't let it for the
others...

> >
> > * The "@param" tag should not contain redundant information (such as
> >  preconditions since they must be documented in a "@throws" tag).
> 
> For the rest of this, I would prefer that we stick with our previously
> agreed convention (stated in the doc above) to just follow the Sun
> conventions.  It will be much easier for contributors and those
> applying patches if we just follow the standard conventions.

The problem (which I suggested to solve with _small_ a "check list" tailored
for CM code is that the standard is sometimes not consistent (IMO), as
examplified in this excerpt of the document you referred to:

-----
When writing the comments themselves, in general, start with a phrase and
follow it with sentences if they are needed.

    * When writing a phrase, do not capitalize and do not end with a period:
        @param x  the x-coordinate, measured in pixels

    * When writing a phrase followed by a sentence, do not capitalize the
    * phrase, but end it with a period to distinguish it from the start of
    * the next sentence:
        @param x  the x-coordinate. Measured in pixels.

    * If you prefer starting with a sentence, capitalize it and end it with
    * a period:
        @param x  Specifies the x-coordinate, measured in pixels.

    * When writing multiple sentences, follow normal sentence rules:
        @param x  Specifies the x-coordinate. Measured in pixels.
-----

I find it more esthetic to apply *one* set of rules and not one set here
and another there; the above examples look really messy...
So, for the "@param" tag, I prefer this set:
 * Do not use the article "the".
 * Always capitalize.
 * Write full sentences, with punctuation.

Also, among the things that would make the CM doc more homogeneous, there
would be a list of when to enclose something in a {@code ...} structure.
And it would mention to avoid the "<code>...</code>" construct whereas it
is suggested in the "standard" guidelines document).

> A couple of areas where we have slipped a bit over the years that I
> would rather apply energy to than formatting are the following (from
> the Developers' guide):
> 
> # All component contracts must be fully specified in the javadoc
> class, interface or method comments, including specification of
> acceptable ranges of values, exceptions or special return values.
> # External references or full statements of definitions for all
> mathematical terms used in component documentation must be provided.
> # Implementations should use standard algorithms and references or
> full descriptions of all algorithms should be provided.
> # Additions and enhancements should include updates to the User Guide.

This is all OK, of course. But what I had in mind is more of a "cheat
sheet", that can be checked easily by the developer (and maybe partly by
CheckStyle?) so that we can be sure that the doc is both complete and a
pleasant read (which, I'm convinced, is helped by a consistent form).

> [...]

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