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 00:48:05 GMT
On Wed, Jan 12, 2011 at 03:23:59PM -0800, Ted Dunning wrote:
> I personally find it more aesthetic and much more expedient to use a
> standard style guide that many people are already familiar with (more or
> less, often less).
> 
> Making up a new style guide is a waste of breath and subject to minor
> aesthetic quibbles like whether to use a phrase.  The Sun guides are
> generally very good and where they have minor issues, the virtue of being an
> accepted standard trumps everything else.  For one thing, we can do
> something productive in the code rather than argue about grammar and
> punctuation.

Maybe I was not quite clear: There is no uniformly applied style in the
Javadoc comments in Commons-Math; if there were, I wouldn't have raised the
issue (and I wouldn't have had to spend hours cleaning up inconsistent
formatting).
If aesthetic documentation were not productive, there wouldn't be editors
and publishers taking care of this aspect, and we would all be content to
read scanned manuscripts.

> On Wed, Jan 12, 2011 at 2:32 PM, Gilles Sadowski <
> gilles@harfang.homelinux.org> wrote:
> 
> > 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.

If the above rules are not obviously clearer, more concise (and more
aesthetic) than the excerpt of the standard rules which I quoted in the
previous post, then I'm indeed wasting my breath.


Gilles

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


Mime
View raw message