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 < > gil...@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-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
