Mailing-List: contact dev-help@commons.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Commons Developers List" <dev@commons.apache.org>
Received-SPF: pass (nike.apache.org: domain of phil.steitz@gmail.com
 designates 209.85.214.43 as permitted sender)
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=gamma;
        h=mime-version:in-reply-to:references:date:message-id:subject:from:to
         :content-type:content-transfer-encoding;
        b=X+rXvGQx+8dmuzXD3UfAMrMnRqMnfMD64y1sENiXWpBsEUW2NgzAe0X2Q9gYZFH/5b
         d24Idksvimi0U+6Bdp2M0DgFMqDYCf7eOxFvvrywI2ie4BZmbfqzv6Jqwqnfh0haw8u2
         RYbWlpFQaUl78rglw/UO78eImHPPn+Nz8f7Ig=
MIME-Version: 1.0
In-Reply-To: <20110111151549.GI22299@dusk.harfang.homelinux.org>
References: <20110111151549.GI22299@dusk.harfang.homelinux.org>
Date: Wed, 12 Jan 2011 13:28:05 -0500
Message-ID: <AANLkTinO5_7sohYZ93V-rxYBR++=+Nfa1F0CK-1ug1zA@mail.gmail.com>
Subject: Re: [Math] Coding and documenting guidelines
From: Phil Steitz <phil.steitz@gmail.com>
To: Commons Developers List <dev@commons.apache.org>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable

On Tue, Jan 11, 2011 at 10:15 AM, Gilles Sadowski
<gilles@harfang.homelinux.org> wrote:
> 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; s=
o 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" t=
ag,
> =A0indicating all the possible causes of the exception (such as the
> =A0assumed 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.

>
> * The "@param" tag should not contain redundant information (such as
> =A0preconditions 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.

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.

I have an open action, for example, to define precisely what we mean
by "support" for distributions.   What is important to me is the
content of the javadoc, not so much what elements include what info.
I think, for example, http://s.apache.org/S39 is fine.  In some cases,
the preconditions of a method involve multiple parameters or other
context info so it is more convenient to state them in the main method
description.  Again, the important thing is to clearly state (or
reference) a) relevant mathematical definitions and algorithms b)
preconditions and c) exceptions or NaN returns when preconditions are
not met.

Phil

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