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