You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Sébastien Brisard <se...@m4x.org> on 2012/08/23 12:39:38 UTC
[math] Formatting
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 ?
Sébastien
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Formatting
Posted by sebb <se...@gmail.com>.
On 23 August 2012 12:52, Gilles Sadowski <gi...@harfang.homelinux.org> wrote:
> On Thu, Aug 23, 2012 at 01:25:42PM +0200, Thomas Neidhart wrote:
>> On Thu, Aug 23, 2012 at 1:16 PM, Sébastien Brisard <
>> sebastien.brisard@m4x.org> wrote:
>>
>> > Hi,
>> >
>> > >
>> > > Probably easiest to use the Wiki for this, at least initially.
>> > >
>> > I'm not very fond of the Wiki: maybe I could just start a JIRA ticket,
>> > that would allow recording our discussions.
>> >
>> > > If there are compulsory rules - e.g. no tabs - a reason should be
>> > > given, for example:
>> > > Tab settings vary. This causes alignment issues, so tabs are banned.
>> > >
>> > > Generally it's easier to understand and follow rules if their purpose
>> > > is made explicit.
>> > >
>> > OK, so for all rules, we will try to provide a reason.
>> >
>>
>> It would be nice to have something in common for all commons (sic!)
>> components ;-)
>>
>> It is somehow odd that one has to switch coding style when working on
>> different components
>
> That's certainly strange, but the fact is that the Commons components do not
> have much in common... The codes live separate lives (dependencies, even to
> "sibling" Commons components, is forbidden for CM), and nothing is more tied
> to code than its formatting: I mean, conventions vary slightly from project
> to project, and "Commons" cannot be considered a single programming project.
>
> Let's agree that it would be nice to have a single set of conventions within
> a "src" subdirectory of the repository. [That's already enough to generate a
> sizeable amount of discussions...] ;-)
>
Maybe one way to approach this is to start by listing what types of
formatting conventions are subject to rules.
Within a component each component can decide the exact implementation.
For example, consistent indentation within a file is obviously very
important for readability (vital for Python!).
It's not essential that all components have the same indentation,
though obviously it makes things easier.
In fact, it may be useful to use different indendation levels for
different file types.
XML generally uses more levels of indentation than Java, so having a
smaller indentation makes sense for XML.
> Gilles
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Formatting
Posted by Gilles Sadowski <gi...@harfang.homelinux.org>.
On Thu, Aug 23, 2012 at 01:25:42PM +0200, Thomas Neidhart wrote:
> On Thu, Aug 23, 2012 at 1:16 PM, Sébastien Brisard <
> sebastien.brisard@m4x.org> wrote:
>
> > Hi,
> >
> > >
> > > Probably easiest to use the Wiki for this, at least initially.
> > >
> > I'm not very fond of the Wiki: maybe I could just start a JIRA ticket,
> > that would allow recording our discussions.
> >
> > > If there are compulsory rules - e.g. no tabs - a reason should be
> > > given, for example:
> > > Tab settings vary. This causes alignment issues, so tabs are banned.
> > >
> > > Generally it's easier to understand and follow rules if their purpose
> > > is made explicit.
> > >
> > OK, so for all rules, we will try to provide a reason.
> >
>
> It would be nice to have something in common for all commons (sic!)
> components ;-)
>
> It is somehow odd that one has to switch coding style when working on
> different components
That's certainly strange, but the fact is that the Commons components do not
have much in common... The codes live separate lives (dependencies, even to
"sibling" Commons components, is forbidden for CM), and nothing is more tied
to code than its formatting: I mean, conventions vary slightly from project
to project, and "Commons" cannot be considered a single programming project.
Let's agree that it would be nice to have a single set of conventions within
a "src" subdirectory of the repository. [That's already enough to generate a
sizeable amount of discussions...] ;-)
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Formatting
Posted by Luc Maisonobe <Lu...@free.fr>.
Le 23/08/2012 13:25, Thomas Neidhart a écrit :
> On Thu, Aug 23, 2012 at 1:16 PM, Sébastien Brisard <
> sebastien.brisard@m4x.org> wrote:
>
>> Hi,
>>
>>>
>>> Probably easiest to use the Wiki for this, at least initially.
>>>
>> I'm not very fond of the Wiki: maybe I could just start a JIRA ticket,
>> that would allow recording our discussions.
>>
>>> If there are compulsory rules - e.g. no tabs - a reason should be
>>> given, for example:
>>> Tab settings vary. This causes alignment issues, so tabs are banned.
>>>
>>> Generally it's easier to understand and follow rules if their purpose
>>> is made explicit.
>>>
>> OK, so for all rules, we will try to provide a reason.
>>
>
> It would be nice to have something in common for all commons (sic!)
> components ;-)
>
> It is somehow odd that one has to switch coding style when working on
> different components
As always, here is the link for the style I use in Eclipse for Commons
components. This file can be used as a starting point for discussion. Of
course, we can change these rules if we want.
Link: <http://people.apache.org/~luc/Apache-commons.xml>.
best regards,
Luc
>
> Thomas
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Formatting
Posted by Thomas Neidhart <th...@gmail.com>.
On Thu, Aug 23, 2012 at 1:16 PM, Sébastien Brisard <
sebastien.brisard@m4x.org> wrote:
> Hi,
>
> >
> > Probably easiest to use the Wiki for this, at least initially.
> >
> I'm not very fond of the Wiki: maybe I could just start a JIRA ticket,
> that would allow recording our discussions.
>
> > If there are compulsory rules - e.g. no tabs - a reason should be
> > given, for example:
> > Tab settings vary. This causes alignment issues, so tabs are banned.
> >
> > Generally it's easier to understand and follow rules if their purpose
> > is made explicit.
> >
> OK, so for all rules, we will try to provide a reason.
>
It would be nice to have something in common for all commons (sic!)
components ;-)
It is somehow odd that one has to switch coding style when working on
different components
Thomas
Re: [math] Formatting
Posted by Sébastien Brisard <se...@m4x.org>.
Hi,
>
> Probably easiest to use the Wiki for this, at least initially.
>
I'm not very fond of the Wiki: maybe I could just start a JIRA ticket,
that would allow recording our discussions.
> If there are compulsory rules - e.g. no tabs - a reason should be
> given, for example:
> Tab settings vary. This causes alignment issues, so tabs are banned.
>
> Generally it's easier to understand and follow rules if their purpose
> is made explicit.
>
OK, so for all rules, we will try to provide a reason.
Sébastien
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Formatting
Posted by sebb <se...@gmail.com>.
On 23 August 2012 11:39, Sébastien Brisard <se...@m4x.org> 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 ?
Probably easiest to use the Wiki for this, at least initially.
If there are compulsory rules - e.g. no tabs - a reason should be
given, for example:
Tab settings vary. This causes alignment issues, so tabs are banned.
Generally it's easier to understand and follow rules if their purpose
is made explicit.
> Sébastien
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Formatting
Posted by Sébastien Brisard <se...@m4x.org>.
Hi,
the idea is *not* to come up with dozens of impossible, picky and
useless rules, but a few rules which we do care about, are easily
enforced, and ensure some kind of consistency.
Of course, consistency in code formatting is more easily enforced than
in comments formatting. But I have to say that, like Gilles, I like to
observe *some kind* of consistency in the javadoc of a library, both
as a user and as a developer. I agree with Gilles, it's just like
reading an article. Poorly formatted papers (or presentations) just
hurt my eyes, regardless of the content.
I understand we may have different views on this point, and I agree
that the essential point is certainly that the comment is
understandable (even, as Churchill would say, by native english
speakers!), and useful. I think it's worth having a go coming up with
a limited set of additional rules.
By the way, if you browse through the whole javadoc of CM, you *do*
observe a kind of consistency [1]. So, whether written or not, we *do*
follow some rules.
Anyway, what I proposed was not to set THE LAW, but rather, to build a
list of guidelines, to be discussed with everyone.
Best regards,
Sébastien
[1] although some recent discussions have shown that *I* break some of
these unstated rules... I will do my best to improve on this side. I
think that's proof that written guidelines could help.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Formatting
Posted by Luc Maisonobe <Lu...@free.fr>.
Le 24/08/2012 03:29, Becksfort, Jared a écrit :
>>> [...]
>>>
>>> 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.
>
>> There is friction if everyone wants to stick with his own style.
>> And there is friction when one has to read poorly written code,
>> just the same as if you'd have to read a document with one word in
>> black, then one in red, followed by one in italic, then one in
>> bold, one in a 12-points font, one in 14-points font, one in times
>> and one in roman, etc.
>
>> There is reason for formatting rules: make a pleasant read. People
>> have to make a little effort e.g. to type LaTeX code so that the
>> _reader_ can be more confortable. [And the effort is much less when
>> writing Javadoc.]
>
>> The actual style is not so important as having a _single one_ (per
>> project, per programming language).
>
>> Gilles
>
> Hello,
>
> I recently contributed my first patch last month and have a couple
> more to go, so I figure I can add something to the discussion of
> formatting being a barrier to entry. I was initially a bit surprised
> at how much I code I needed to reformat, but I expected there to be
> some. In retrospect, the initial patch I turned in was a bit sloppy.
> Importantly, though, Gilles paid attention enough to the issue I was
> patching and provided me with some pretty good feedback that
> eventually resulted in committed code. Now as I prepare a couple of
> new patches, I don't think the style is a significant deterrent. It
> definitely would be a deterrent though if patches were just rejected
> outright with little feedback. I realize that requires a bit of a
> commitment on the part of the main developers, so I guess you will
> have to decide how much of a hassle it is. If there are tons of new
> contributors, it might be too much effort, but I imagine that a lot
> of the code comes from repeat contributors and the main developers.
>
> I realize not everyone uses Eclipse, but you can pretty easily set up
> code formatting for individual projects. It also allows for code
> styles to be exported and imported. Maybe it would be helpful to
> make a code style available for download.
There is one here for eclipse:
<http://people.apache.org/~luc/Apache-commons.xml>.
Luc
>
> Jared
>
> Email Disclaimer: www.stjude.org/emaildisclaimer Consultation
> Disclaimer: www.stjude.org/consultationdisclaimer
>
>
> ---------------------------------------------------------------------
>
>
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
RE: [math] Formatting
Posted by "Becksfort, Jared" <Ja...@STJUDE.ORG>.
> > [...]
>>
>> 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.
>There is friction if everyone wants to stick with his own style.
>And there is friction when one has to read poorly written code, just the
>same as if you'd have to read a document with one word in black, then one in
>red, followed by one in italic, then one in bold, one in a 12-points font,
>one in 14-points font, one in times and one in roman, etc.
>There is reason for formatting rules: make a pleasant read. People have to
>make a little effort e.g. to type LaTeX code so that the _reader_ can be
>more confortable. [And the effort is much less when writing Javadoc.]
>The actual style is not so important as having a _single one_ (per project,
>per programming language).
>Gilles
Hello,
I recently contributed my first patch last month and have a couple more to go, so I figure I can add something to the discussion of formatting being a barrier to entry. I was initially a bit surprised at how much I code I needed to reformat, but I expected there to be some. In retrospect, the initial patch I turned in was a bit sloppy. Importantly, though, Gilles paid attention enough to the issue I was patching and provided me with some pretty good feedback that eventually resulted in committed code. Now as I prepare a couple of new patches, I don't think the style is a significant deterrent. It definitely would be a deterrent though if patches were just rejected outright with little feedback. I realize that requires a bit of a commitment on the part of the main developers, so I guess you will have to decide how much of a hassle it is. If there are tons of new contributors, it might be too much effort, but I imagine that a lot of the code comes from repeat contributors and the main developers.
I realize not everyone uses Eclipse, but you can pretty easily set up code formatting for individual projects. It also allows for code styles to be exported and imported. Maybe it would be helpful to make a code style available for download.
Jared
Email Disclaimer: www.stjude.org/emaildisclaimer
Consultation Disclaimer: www.stjude.org/consultationdisclaimer
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Formatting
Posted by Gilles Sadowski <gi...@harfang.homelinux.org>.
> > [...]
>
> 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.
There is friction if everyone wants to stick with his own style.
And there is friction when one has to read poorly written code, just the
same as if you'd have to read a document with one word in black, then one in
red, followed by one in italic, then one in bold, one in a 12-points font,
one in 14-points font, one in times and one in roman, etc.
There is reason for formatting rules: make a pleasant read. People have to
make a little effort e.g. to type LaTeX code so that the _reader_ can be
more confortable. [And the effort is much less when writing Javadoc.]
The actual style is not so important as having a _single one_ (per project,
per programming language).
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Formatting
Posted by "Honton, Charles" <Ch...@intuit.com>.
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" <ph...@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-unsubscribe@commons.apache.org
>> For additional commands, e-mail: dev-help@commons.apache.org
>>
>>
>
>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>For additional commands, e-mail: dev-help@commons.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Formatting
Posted by Phil Steitz <ph...@gmail.com>.
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-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] Formatting
Posted by Gilles Sadowski <gi...@harfang.homelinux.org>.
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
Re: [math] Formatting
Posted by Phil Steitz <ph...@gmail.com>.
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.
Phil
> Sébastien
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org