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] Formatting
Date Thu, 23 Aug 2012 23:02:20 GMT
On Thu, Aug 23, 2012 at 02:15:58PM -0700, Phil Steitz wrote:
> On 8/23/12 3:39 AM, S├ębastien Brisard wrote:
> > Hi,
> > in MATH-851, a discussion about code- and comments-formatting as yet
> > again taken place. It is true we are a bit fuzzy on this side. I
> > propose to start writing something up in the developer's guide. This
> > will be a start, and every one of you could then comment on these
> > guidelines.
> > The idea is to gather the compulsory rules, as well as some optional
> > rules, which should then be complemented by the rationale for these
> > optional rules.
> >
> > What do you think ?
> 
> I have only one comment:
> 
> fewer rules == better
> 
> More rules mean more stuff to worry about cleaning up.  Putting the
> onus on contributors to follow lots of picky formatting and style
> rules presents a barrier to contribution.  Having to fix lots of
> inconsequential formatting stuff is a waste of time that I would
> prefer not to spend in preparing my own commits or reviewing and
> applying patches by others.
> 
> No tabs is a good rule because they screw up diffs.  Having good and
> meaningful javadoc is a good rule because it makes the software
> easier to use and maintain.  Counting spaces, how to use articles,
> what to capitalize - not worth standardizing and not a good thing to
> do in OSS, IMO.

Our mileage still vary. All of the above is similar to the difference
between reading a document created by an inconsequent user of M$-Word and a
document typeset with LaTeX.

Nicely formatted code and documentation is _not_ more effort, and does make
a difference when reading it, for me anyways, and probably also for other
potential contributors. It doesn't for users-only, but they are not the ones
who are going to have to read the code in order to try and fix bugs.

[No tab is a good rule because it makes code _readable_ independently of
one's particular tab setting.]

Some rules are enforced by CheckStyle for no particularly "intelligent"
reason other than plain consistency. And this is reason enough.


Gilles

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


Mime
View raw message