commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Steitz <phil.ste...@gmail.com>
Subject Re: [Math] Coding and documenting guidelines
Date Thu, 13 Jan 2011 00:44:22 GMT
On Wed, Jan 12, 2011 at 5:32 PM, 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; 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...
>
+1 here - I agree completely.  If we are consistent here, the code
will be maintainable.  This is what is meant by the statement in the
Developer Guide that I quoted above about documenting exceptions.

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

Your ideas for modifying the Sun standard are interesting.
Personally, I prefer to stick with the standard, for the reason that
others have stated that it is easier for contributors to follow and
creates less work modifying patches (and new code) to comply.  As I
said above, I would much rather see effort go into filling in the gaps
and clarifying the imprecision in the content of the javadoc (both
existing and that which comes with patches) than to "standardizing"
format.  Lets see what others in the community think.

Phil

>> [...]
>
> Regards,
> Gilles
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>

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


Mime
View raw message