commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Honton, Charles" <>
Subject Re: [math] Formatting
Date Thu, 23 Aug 2012 23:54:15 GMT
It's also important that the diff can be applied.  The less consistent the
formatting is, the less likely that patch will succeed.


On 8/23/12 4:11 PM, "Phil Steitz" <> 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
>> a difference when reading it, for me anyways, and probably also for
>> potential contributors. It doesn't for users-only, but they are not the
>> 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.
>> [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:
>> For additional commands, e-mail:
>To unsubscribe, e-mail:
>For additional commands, e-mail:

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message