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
