commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Steitz <>
Subject Re: [Math] Coding and documenting guidelines
Date Thu, 13 Jan 2011 15:34:00 GMT

On Jan 13, 2011, at 7:21 AM, Gilles Sadowski <> wrote:

> Hi.
>> [...]
>>>> 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.
> So, together, we say that both formatting and contents need improvement.
> Since they are not contradicting goals, both can be achieved.

Yes, though I don't see big problems with formatting and I don't see the need - and in fact
see reasons not to - depart from the established standard or add more requirements that contributors
need to follow. 

> We can diverge as to their respective priority, as far as the upgrade of
> existing code is concerned.
> But what I'm suggesting is to lay out simple and concise rules (by
> extracting the relevant part of the "standard", if need be) so that from now
> on, the changes (code and doc) are provided in the best possible form.
My personal view is that the standard is fine as is. If others agree with your suggested changes
and are willing to sign up for the associated maintenance, we can agree on and make changes
to the Developer Guide.

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

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

View raw message