commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gilles Sadowski <>
Subject Re: [Math] Coding and documenting guidelines
Date Thu, 13 Jan 2011 12:21:19 GMT

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

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.


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

View raw message