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 Thu, 13 Jan 2011 16:07:07 GMT
On Thu, Jan 13, 2011 at 10:34:00AM -0500, Phil Steitz wrote:
> 
> 
> 
> 
> On Jan 13, 2011, at 7:21 AM, Gilles Sadowski <gilles@harfang.homelinux.org> 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. 

There are no big problems, just a lot of small ones (e.g. using a keywords
like "null" without writing it as "{@code null}" and some comments being
complete sentences while others aren't).
If this is not important (again, I'm not saying it should be high-priority),
then I'd strongly suggest to remove the "trailing white space" rule from
CheckStyle because that one should be orders of magnitude less important...

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

The standard may be fine; it's just not applied everywhere in the doc,
that's the point: Whatever the rules, it should be easy to check a block of
Javadoc comment against the cheat sheet and to conclude that "Rule 1, 3 and
9 are violated."


Gilles

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


Mime
View raw message