It's also important that the diff can be applied. The less consistent the formatting is, the less likely that patch will succeed.
chas On 8/23/12 4:11 PM, "Phil Steitz" <phil.ste...@gmail.com> wrote: >On 8/23/12 4:02 PM, Gilles Sadowski wrote: >> 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. > >Think about it from the standpoint of a new contributor. How long >does it take to prepare and get a patch committed for a) the new >contributor and b) the committer who ends up applying the patch. >More rules means more time. It is that simple. Either the new >contributor has to keep fixing his or her patch so it complies with >all of the rules or the committer applying it does that. In either >case, friction is introduced. Fewer rules means less friction, >which IMO is more important than cosmetics. > >Phil >> >> [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 >> >> > > >--------------------------------------------------------------------- >To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org >For additional commands, e-mail: dev-h...@commons.apache.org > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
