You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@stanbol.apache.org by Olivier Grisel <ol...@ensta.org> on 2010/12/12 16:37:06 UTC
[VOTE] code conventions for stanbol project
Hi all,
I think we should adopt the same code conventions as other established
apache projects: Lucene, Solr and Mahout all use the Sun official code
conventions with the exception of using 2 spaces indents instead of 4.
http://www.oracle.com/technetwork/java/codeconv-138413.html
There is an eclipse code formatter (along with an unmaintained idea
version) here:
https://cwiki.apache.org/confluence/display/MAHOUT/How+To+Contribute#HowToContribute-HelpfulResources
The whole wiki page HowToContribute on Mahout's wiki is worth a read
too (many practical details on how to make and apply a patch for
instance):
https://cwiki.apache.org/confluence/display/MAHOUT/How+To+Contribute
The same formatters from the Apache Lucene / Solr projects are available
here:
http://wiki.apache.org/solr/HowToContribute?action=AttachFile
Note you are off-course free to use another editor / IDE, I just mention this
as a convenience for the majority of the developers that seam to use eclipse.
Please vote with +1 / -1 in reply to this thread. If you are not a
project committer please add "(unbinding)" next to your vote.
If those conventions are accepted I would like to do a batch reformat of the
existing stanbol codebase using this formatter next week.
--
Olivier
http://twitter.com/ogrisel - http://github.com/ogrisel
Re: [VOTE] code conventions for stanbol project
Posted by Bertrand Delacretaz <bd...@apache.org>.
On Mon, Dec 13, 2010 at 11:28 AM, Stefane Fermigier <sf...@nuxeo.com> wrote:
> On Dec 13, 2010, at 10:22 AM, Bertrand Delacretaz wrote:
>>... My advice is: if you just change a few lines in an existing file, just
>> follow that file's style. And above all don't mix reformatting and
>> code changes in commits as I said elsewhere.
>
> I agree that when you are a newcomer to an existing code base, you should by all mean refrain from reformatting the code to your own taste, if the code base already uses a consistent convention.
>
> OTOH, I think it gives a very bad impression to newcomers or people that just want to study your code (for some reason, including evaluating it for their own use) if they find that you're using very inconsistent styles in your code base, i.e. tabs vs spaces, 2 vs 4 indents, 1TBS (http://en.wikipedia.org/wiki/Indent_style#Variant:_1TBS) vs. Allman, etc.
I agree that being very inconsistent would be bad...for now I suggest
starting with the suggested reformatting and come back to this if we
see problems.
-Bertrand
Re: [VOTE] code conventions for stanbol project
Posted by Stefane Fermigier <sf...@nuxeo.com>.
On Dec 13, 2010, at 10:22 AM, Bertrand Delacretaz wrote:
> On Mon, Dec 13, 2010 at 10:03 AM, Fabian Christ
> <ch...@googlemail.com> wrote:
>> 2010/12/13 Rupert Westenthaler <rw...@apache.org>:
>>> ...I would suggest to exclude this point and allow longer lines than 80
>>> chars...
>
>> Yes, I agree with Rupert. I normally don't use any auto line break at
>> all and set line length to 999....
>
> Agreed...for me "something around the width of a modern display" is fine.
As I said, *my* modern IDE has 120 chars, and when I edit code with vi in a console, or TextMate I even have only 80 characters.
So the 80-120 rules makes sense to me, and I don't think I'm the exception.
> I don't care much about 2 or 4 spaces for indents, usually use 4. But
> no tabs, agreed.
>
> In general, my opinion is to avoid being religious on these things,
> and above all avoid needlessly reformatting source code (initial
> cleanup like we're doing now is fine of course).
Agreed.
> My advice is: if you just change a few lines in an existing file, just
> follow that file's style. And above all don't mix reformatting and
> code changes in commits as I said elsewhere.
I agree that when you are a newcomer to an existing code base, you should by all mean refrain from reformatting the code to your own taste, if the code base already uses a consistent convention.
OTOH, I think it gives a very bad impression to newcomers or people that just want to study your code (for some reason, including evaluating it for their own use) if they find that you're using very inconsistent styles in your code base, i.e. tabs vs spaces, 2 vs 4 indents, 1TBS (http://en.wikipedia.org/wiki/Indent_style#Variant:_1TBS) vs. Allman, etc.
> That being said, +1 on the proposed "rules" - which I'm sure you'll
> see me break where it makes sense ;-)
No problem with breaking the rules when it's done with taste and only exceptionally.
S.
--
Stefane Fermigier, Founder and Chairman, Nuxeo
Open Source, Java EE based, Enterprise Content Management (ECM)
http://www.nuxeo.com/ - +33 1 40 33 79 87 - http://twitter.com/sfermigier
Join the Nuxeo Group on LinkedIn: http://linkedin.com/groups?gid=43314
New Nuxeo release: http://nuxeo.com/dm54
"There's no such thing as can't. You always have a choice."
Re: [VOTE] code conventions for stanbol project
Posted by Bertrand Delacretaz <bd...@apache.org>.
On Mon, Dec 13, 2010 at 10:03 AM, Fabian Christ
<ch...@googlemail.com> wrote:
> 2010/12/13 Rupert Westenthaler <rw...@apache.org>:
>> ...I would suggest to exclude this point and allow longer lines than 80
>> chars...
> Yes, I agree with Rupert. I normally don't use any auto line break at
> all and set line length to 999....
Agreed...for me "something around the width of a modern display" is fine.
I don't care much about 2 or 4 spaces for indents, usually use 4. But
no tabs, agreed.
In general, my opinion is to avoid being religious on these things,
and above all avoid needlessly reformatting source code (initial
cleanup like we're doing now is fine of course).
My advice is: if you just change a few lines in an existing file, just
follow that file's style. And above all don't mix reformatting and
code changes in commits as I said elsewhere.
That being said, +1 on the proposed "rules" - which I'm sure you'll
see me break where it makes sense ;-)
-Bertrand
Re: [VOTE] code conventions for stanbol project
Posted by Fabian Christ <ch...@googlemail.com>.
Hi,
2010/12/13 Rupert Westenthaler <rw...@apache.org>:
> Line length (section Sun code conventions 4.1)
>
> I would suggest to exclude this point and allow longer lines than 80
> chars. The argument about terminals is no longer valid nowadays and
> with typical screen resolutions even lines with 150 chars do fit well.
> Especially breaking up long log messages into several lines makes the
> code much harder to read in my opinion.
Yes, I agree with Rupert. I normally don't use any auto line break at
all and set line length to 999.
Best,
--
Fabian
Re: [VOTE] code conventions for stanbol project
Posted by Stefane Fermigier <sf...@nuxeo.com>.
On Dec 13, 2010, at 11:39 AM, Bertrand Delacretaz wrote:
> On Mon, Dec 13, 2010 at 11:33 AM, Stefane Fermigier <sf...@nuxeo.com> wrote:
>> On Dec 13, 2010, at 11:30 AM, Bertrand Delacretaz wrote:
> ...
>>> http://incubator.apache.org/rat/ is useful to check headers before a
>>> release, but I'm not sure what the use case is for a maven license
>>> headers plugin.
>>
>> I can see 3 different use cases:
>>
>> 1. Check that all your source code files have some kind of header, with some rules (for instance regarding the copyright years, etc.)
>>
>> 2. Add a given header to your files when it's missing, according to some rules.
>>
>> 3. Report on the various license types used in your headers, so as to check you don't have some legal issue.
>
> RAT does 1. and 3., it's the official ASF tool and IIRC there's a
> Maven plugin for it.
Cool.
> If someone wants to integrate it in our build I'm fine with that,
> otherwise it's easy to run it manually when preparing a release.
I have a Python script that does 2. (taylored for the Nuxeo code base, but easy to change).
But it's possible that either Eclipse or IDEA (or Netbeans) has this function built-in. Maybe someone with more knowledge than I can answer ?
S.
--
Stefane Fermigier, Founder and Chairman, Nuxeo
Open Source, Java EE based, Enterprise Content Management (ECM)
http://www.nuxeo.com/ - +33 1 40 33 79 87 - http://twitter.com/sfermigier
Join the Nuxeo Group on LinkedIn: http://linkedin.com/groups?gid=43314
New Nuxeo release: http://nuxeo.com/dm54
"There's no such thing as can't. You always have a choice."
Re: [VOTE] code conventions for stanbol project
Posted by Bertrand Delacretaz <bd...@apache.org>.
On Mon, Dec 13, 2010 at 11:33 AM, Stefane Fermigier <sf...@nuxeo.com> wrote:
> On Dec 13, 2010, at 11:30 AM, Bertrand Delacretaz wrote:
...
>> http://incubator.apache.org/rat/ is useful to check headers before a
>> release, but I'm not sure what the use case is for a maven license
>> headers plugin.
>
> I can see 3 different use cases:
>
> 1. Check that all your source code files have some kind of header, with some rules (for instance regarding the copyright years, etc.)
>
> 2. Add a given header to your files when it's missing, according to some rules.
>
> 3. Report on the various license types used in your headers, so as to check you don't have some legal issue.
RAT does 1. and 3., it's the official ASF tool and IIRC there's a
Maven plugin for it.
If someone wants to integrate it in our build I'm fine with that,
otherwise it's easy to run it manually when preparing a release.
-Bertrand
Re: [VOTE] code conventions for stanbol project
Posted by Stefane Fermigier <sf...@nuxeo.com>.
On Dec 13, 2010, at 11:30 AM, Bertrand Delacretaz wrote:
> On Mon, Dec 13, 2010 at 11:21 AM, Stefane Fermigier <sf...@nuxeo.com> wrote:
>> On Dec 13, 2010, at 9:48 AM, Rupert Westenthaler wrote:
>>> License Headers
>>>
>>> A short google search for "mvn plugin license" showed up several
>>> options for plugin that are able to manage license headers. I suggest
>>> to use one of those.
>>
>>
>> I'm sure Bertrand knows the best one to use :)...
>
> Er....no, why would we use a plugin to manage license headers?
>
> http://incubator.apache.org/rat/ is useful to check headers before a
> release, but I'm not sure what the use case is for a maven license
> headers plugin.
I can see 3 different use cases:
1. Check that all your source code files have some kind of header, with some rules (for instance regarding the copyright years, etc.)
2. Add a given header to your files when it's missing, according to some rules.
3. Report on the various license types used in your headers, so as to check you don't have some legal issue.
S.
--
Stefane Fermigier, Founder and Chairman, Nuxeo
Open Source, Java EE based, Enterprise Content Management (ECM)
http://www.nuxeo.com/ - +33 1 40 33 79 87 - http://twitter.com/sfermigier
Join the Nuxeo Group on LinkedIn: http://linkedin.com/groups?gid=43314
New Nuxeo release: http://nuxeo.com/dm54
"There's no such thing as can't. You always have a choice."
Re: [VOTE] code conventions for stanbol project
Posted by Bertrand Delacretaz <bd...@apache.org>.
On Mon, Dec 13, 2010 at 11:21 AM, Stefane Fermigier <sf...@nuxeo.com> wrote:
> On Dec 13, 2010, at 9:48 AM, Rupert Westenthaler wrote:
>> License Headers
>>
>> A short google search for "mvn plugin license" showed up several
>> options for plugin that are able to manage license headers. I suggest
>> to use one of those.
>
>
> I'm sure Bertrand knows the best one to use :)...
Er....no, why would we use a plugin to manage license headers?
http://incubator.apache.org/rat/ is useful to check headers before a
release, but I'm not sure what the use case is for a maven license
headers plugin.
-Bertrand
Re: [VOTE] code conventions for stanbol project
Posted by Enrico Daga <en...@gmail.com>.
Hi,
I also agree (+1) on having shared code conventions, no matter 2 or 4 indent.
I also use eclipse, so it's ok to use the formatter posted by Olivier.
Enrico
On 14 December 2010 16:13, Fabian Christ <ch...@googlemail.com> wrote:
> Hi,
>
> I am +1 for any convention no matter if 2 or 4 indent. I am fine with
> the last version Olivier sent around.
>
> Best,
> - Fabian
>
> 2010/12/14 Stefane Fermigier <sf...@nuxeo.com>:
>>
>> On Dec 14, 2010, at 3:50 PM, Bertrand Delacretaz wrote:
>>
>>> Hi,
>>>
>>> On Tue, Dec 14, 2010 at 3:35 PM, Olivier Grisel
>>> <ol...@ensta.org> wrote:
>>>> ...Could people who voted -1 (or expressed negative comments on this),
>>>> please give feedback or propose an alternative eclipse formatter file?
>>>> We really need to reach a consensus soon on this....
>>>
>>> To reiterate my position: I'm +1 on the basic formatting that you
>>> suggest, either with 2 or 4 spaces as people prefer. To be frank I
>>> didn't even test it, I just trust you ;-)
>>>
>>> But I'm -1 on being religious about this: once we have a clean state
>>> after someone does the initial reformatting, I would hate to see
>>> commits rejected because they do not abide by The Rules - common sense
>>> should prevail.
>>
>> No problem with that.
>>
>> Can we vote on spaces (2 or 4) ?
>>
>> Here's a doodle for that:
>>
>> http://doodle.com/zsesf72x3xqndp9s
>>
>> (Unless it's against the Apache rules to vote with a Doodle).
>>
>> S.
>>
>> --
>> Stefane Fermigier, Founder and Chairman, Nuxeo
>> Open Source, Java EE based, Enterprise Content Management (ECM)
>> http://www.nuxeo.com/ - +33 1 40 33 79 87 - http://twitter.com/sfermigier
>> Join the Nuxeo Group on LinkedIn: http://linkedin.com/groups?gid=43314
>> New Nuxeo release: http://nuxeo.com/dm54
>> "There's no such thing as can't. You always have a choice."
>>
>>
>
>
>
> --
> Fabian
>
--
Enrico Daga
Technology Expert
--
Ufficio Sistemi Informativi (DCSPI-USI)
National Research Council (CNR)
P.le Aldo Moro 7 - Rome, Italy
Tel +39 4993 3321
--
Semantic Technology Laboratory (STLab)
Institute for Cognitive Science and Technology (ISTC-CNR)
Via Nomentana 56, Rome - Italy
--
http://stlab.istc.cnr.it/stlab/User:EnricoDaga
http://www.enridaga.net
skype: enri-pan
Re: [VOTE] code conventions for stanbol project
Posted by Tommaso Teofili <to...@gmail.com>.
same here: I am keen to go on with the last Olivier proposal, however I've
seen projects with both tab or space (2 or 4) based code formatting and in
the end, in my opinion, it doesn't really make the code/project quality
better or worse.
Tommaso
2010/12/14 Fabian Christ <ch...@googlemail.com>
> Hi,
>
> I am +1 for any convention no matter if 2 or 4 indent. I am fine with
> the last version Olivier sent around.
>
> Best,
> - Fabian
>
> 2010/12/14 Stefane Fermigier <sf...@nuxeo.com>:
> >
> > On Dec 14, 2010, at 3:50 PM, Bertrand Delacretaz wrote:
> >
> >> Hi,
> >>
> >> On Tue, Dec 14, 2010 at 3:35 PM, Olivier Grisel
> >> <ol...@ensta.org> wrote:
> >>> ...Could people who voted -1 (or expressed negative comments on this),
> >>> please give feedback or propose an alternative eclipse formatter file?
> >>> We really need to reach a consensus soon on this....
> >>
> >> To reiterate my position: I'm +1 on the basic formatting that you
> >> suggest, either with 2 or 4 spaces as people prefer. To be frank I
> >> didn't even test it, I just trust you ;-)
> >>
> >> But I'm -1 on being religious about this: once we have a clean state
> >> after someone does the initial reformatting, I would hate to see
> >> commits rejected because they do not abide by The Rules - common sense
> >> should prevail.
> >
> > No problem with that.
> >
> > Can we vote on spaces (2 or 4) ?
> >
> > Here's a doodle for that:
> >
> > http://doodle.com/zsesf72x3xqndp9s
> >
> > (Unless it's against the Apache rules to vote with a Doodle).
> >
> > S.
> >
> > --
> > Stefane Fermigier, Founder and Chairman, Nuxeo
> > Open Source, Java EE based, Enterprise Content Management (ECM)
> > http://www.nuxeo.com/ - +33 1 40 33 79 87 -
> http://twitter.com/sfermigier
> > Join the Nuxeo Group on LinkedIn: http://linkedin.com/groups?gid=43314
> > New Nuxeo release: http://nuxeo.com/dm54
> > "There's no such thing as can't. You always have a choice."
> >
> >
>
>
>
> --
> Fabian
>
Re: [VOTE] code conventions for stanbol project
Posted by Fabian Christ <ch...@googlemail.com>.
Hi,
I am +1 for any convention no matter if 2 or 4 indent. I am fine with
the last version Olivier sent around.
Best,
- Fabian
2010/12/14 Stefane Fermigier <sf...@nuxeo.com>:
>
> On Dec 14, 2010, at 3:50 PM, Bertrand Delacretaz wrote:
>
>> Hi,
>>
>> On Tue, Dec 14, 2010 at 3:35 PM, Olivier Grisel
>> <ol...@ensta.org> wrote:
>>> ...Could people who voted -1 (or expressed negative comments on this),
>>> please give feedback or propose an alternative eclipse formatter file?
>>> We really need to reach a consensus soon on this....
>>
>> To reiterate my position: I'm +1 on the basic formatting that you
>> suggest, either with 2 or 4 spaces as people prefer. To be frank I
>> didn't even test it, I just trust you ;-)
>>
>> But I'm -1 on being religious about this: once we have a clean state
>> after someone does the initial reformatting, I would hate to see
>> commits rejected because they do not abide by The Rules - common sense
>> should prevail.
>
> No problem with that.
>
> Can we vote on spaces (2 or 4) ?
>
> Here's a doodle for that:
>
> http://doodle.com/zsesf72x3xqndp9s
>
> (Unless it's against the Apache rules to vote with a Doodle).
>
> S.
>
> --
> Stefane Fermigier, Founder and Chairman, Nuxeo
> Open Source, Java EE based, Enterprise Content Management (ECM)
> http://www.nuxeo.com/ - +33 1 40 33 79 87 - http://twitter.com/sfermigier
> Join the Nuxeo Group on LinkedIn: http://linkedin.com/groups?gid=43314
> New Nuxeo release: http://nuxeo.com/dm54
> "There's no such thing as can't. You always have a choice."
>
>
--
Fabian
Re: [VOTE] code conventions for stanbol project
Posted by Bertrand Delacretaz <bd...@apache.org>.
On Tue, Dec 14, 2010 at 4:05 PM, Stefane Fermigier <sf...@nuxeo.com> wrote:
> ...Can we vote on spaces (2 or 4) ?
>
> Here's a doodle for that:
>
> http://doodle.com/zsesf72x3xqndp9s
>
> (Unless it's against the Apache rules to vote with a Doodle)...
It is against the "everything must happen on the dev list" rule,
because such a vote won't be visible in the mailing list archives of
this list, and all decisions must be there.
I'll start another vote thread for the 2 or 4 spaces...of course for
such a small decision that's somewhat bureaucratic, but we're a young
podling and youngsters must do All Things Right ;-)
-Bertrand
Re: [VOTE] code conventions for stanbol project
Posted by Stefane Fermigier <sf...@nuxeo.com>.
On Dec 14, 2010, at 3:50 PM, Bertrand Delacretaz wrote:
> Hi,
>
> On Tue, Dec 14, 2010 at 3:35 PM, Olivier Grisel
> <ol...@ensta.org> wrote:
>> ...Could people who voted -1 (or expressed negative comments on this),
>> please give feedback or propose an alternative eclipse formatter file?
>> We really need to reach a consensus soon on this....
>
> To reiterate my position: I'm +1 on the basic formatting that you
> suggest, either with 2 or 4 spaces as people prefer. To be frank I
> didn't even test it, I just trust you ;-)
>
> But I'm -1 on being religious about this: once we have a clean state
> after someone does the initial reformatting, I would hate to see
> commits rejected because they do not abide by The Rules - common sense
> should prevail.
No problem with that.
Can we vote on spaces (2 or 4) ?
Here's a doodle for that:
http://doodle.com/zsesf72x3xqndp9s
(Unless it's against the Apache rules to vote with a Doodle).
S.
--
Stefane Fermigier, Founder and Chairman, Nuxeo
Open Source, Java EE based, Enterprise Content Management (ECM)
http://www.nuxeo.com/ - +33 1 40 33 79 87 - http://twitter.com/sfermigier
Join the Nuxeo Group on LinkedIn: http://linkedin.com/groups?gid=43314
New Nuxeo release: http://nuxeo.com/dm54
"There's no such thing as can't. You always have a choice."
Re: [VOTE] code conventions for stanbol project
Posted by Olivier Grisel <ol...@ensta.org>.
2010/12/14 Bertrand Delacretaz <bd...@apache.org>:
> Hi,
>
> On Tue, Dec 14, 2010 at 3:35 PM, Olivier Grisel
> <ol...@ensta.org> wrote:
>> ...Could people who voted -1 (or expressed negative comments on this),
>> please give feedback or propose an alternative eclipse formatter file?
>> We really need to reach a consensus soon on this....
>
> To reiterate my position: I'm +1 on the basic formatting that you
> suggest, either with 2 or 4 spaces as people prefer. To be frank I
> didn't even test it, I just trust you ;-)
>
> But I'm -1 on being religious about this: once we have a clean state
> after someone does the initial reformatting, I would hate to see
> commits rejected because they do not abide by The Rules - common sense
> should prevail.
I don't want to reject any commits but I would like to avoid having
checkins on the same file alternate between two personal conventions
because of a taste clash.
However there is something I really don't like about the formatter of
Mahout: it indents the empty lines adding many unnecessary trailing
spaces. I would rather disable this in the formatter as done in the
attached version of the formatter.
--
Olivier
http://twitter.com/ogrisel - http://github.com/ogrisel
Re: [VOTE] code conventions for stanbol project
Posted by Bertrand Delacretaz <bd...@apache.org>.
Hi,
On Tue, Dec 14, 2010 at 3:35 PM, Olivier Grisel
<ol...@ensta.org> wrote:
> ...Could people who voted -1 (or expressed negative comments on this),
> please give feedback or propose an alternative eclipse formatter file?
> We really need to reach a consensus soon on this....
To reiterate my position: I'm +1 on the basic formatting that you
suggest, either with 2 or 4 spaces as people prefer. To be frank I
didn't even test it, I just trust you ;-)
But I'm -1 on being religious about this: once we have a clean state
after someone does the initial reformatting, I would hate to see
commits rejected because they do not abide by The Rules - common sense
should prevail.
-Bertrand
Re: [VOTE] code conventions for stanbol project
Posted by Olivier Grisel <ol...@ensta.org>.
2010/12/13 Olivier Grisel <ol...@ensta.org>:
>
> I agree with SF that columns soft and hard limits really helps
> readability a lot: this is really the only valid reason.
>
> Also I can not stress enough the importance of using existing widely
> used code conventions: If we use the conventions that most people use
> in other project they will feel at home when reading our code base.
> This is really important to attract new contributors and blend well
> with the rest of the community.
So what do we do about the code conventions? I think this is really
important that we are consistent both internally (inside the stanbol
project) and external (with established project that might be related
to us such as apache solr and mahout).
Please try to apply the formatter to a project for testing:
Save the following as a file named Mahout-Eclipse-Codeformatter.xml on your HDD:
https://cwiki.apache.org/confluence/download/attachments/74839/Mahout-Eclipse-Codeformatter.xml?version=1&modificationDate=1266109560000
Ensure that you have no local changes on your stanbol source tree,
then go to eclipse and right click on the one of the stanbol projects:
Properties > Java Code Style > Formatter
click "Enabled project specific settings" and then "Import..." and
select the Mahout-Eclipse-Codeformatter.xml file and apply.
Then go to a class of this project and format it using the keyboard
shortcut "Shift-Ctrl-F". See the results and then revert your changes
with "svn revert" (do not check in formatting before we reach a
consensus).
This formatter uses 2 spaces for indenting and 110 columns wrapping.
Though I tend to prefer the conventions we use in nuxeo by personal
taste, I think it is more important to be consistent with what the
majority is using in the apache community. The real value of code
conventions lies in there ability to be shared with many projects.
Could people who voted -1 (or expressed negative comments on this),
please give feedback or propose an alternative eclipse formatter file?
We really need to reach a consensus soon on this.
I think that the current state on the code base is really messy and we
need to agree on some style conventions before starting the big
package name refactoring.
--
Olivier
http://twitter.com/ogrisel - http://github.com/ogrisel
Re: [VOTE] code conventions for stanbol project
Posted by Olivier Grisel <ol...@ensta.org>.
2010/12/13 Stefane Fermigier <sf...@nuxeo.com>:
I agree with SF that columns soft and hard limits really helps
readability a lot: this is really the only valid reason.
Also I can not stress enough the importance of using existing widely
used code conventions: If we use the conventions that most people use
in other project they will feel at home when reading our code base.
This is really important to attract new contributors and blend well
with the rest of the community.
--
Olivier
http://twitter.com/ogrisel - http://github.com/ogrisel
Re: [VOTE] code conventions for stanbol project
Posted by Stefane Fermigier <sf...@nuxeo.com>.
On Dec 13, 2010, at 9:48 AM, Rupert Westenthaler wrote:
> Hi all,
>
> no vote yet, but let me add some comments:
>
> Line length (section Sun code conventions 4.1)
>
> I would suggest to exclude this point and allow longer lines than 80
> chars. The argument about terminals is no longer valid nowadays and
> with typical screen resolutions even lines with 150 chars do fit well.
On my 13'' Mac Book, which is a pretty standard machine nowadays, using IDEA as my IDE, with a standard font site, I have about 120 horizontal characters in the editor windows (when the left navigation panel is open, which for me is all the time), not 150.
> Especially breaking up long log messages into several lines makes the
> code much harder to read in my opinion.
I don't agree with this statement.
Long established typographical knowledge (based on empirical evidences) suggests lines should be around 50 to 60 characters long, maximum 70, for maximal readability.
See for instance:
http://baymard.com/blog/line-length-readability
and the references given therein.
So the old-time recommendation for using 80 characters wide lines (which was mandated by the use of obsolete computer equipment such as the Teletype or VT-100 terminal) still makes sense. This is specially true for logging messages that should be treated as regular text, here obey the rule of typography.
I agree that forcing Java code to be 80 characters wide can lead to something that's unappealing, specially when you have long method names, and using generics.
OTOH, if you end up with lines too long to fit into 80 characters, it can mean that:
- you're using too nested for / while / if statements, that should be decomposed into smaller methods (see for instance Clean Code by Bob Martin, http://en.wikipedia.org/wiki/Special:BookSources/0132350882 ).
- you're using too complex expressions, that should be decomposed in simpler expressions with additional variables (same reference).
To summarize, I think we should treat 80 characters as a "soft" limit (i.e. we should *try* to fit our code into 80 characters) and 120 (not 150!) as a "hard" limit, except for very special cases (i.e. code that's not supposed to be read at all).
> Intend size
>
> I have done some testing based on the suggested code formatter
> configuration. In general the 4 spaces intend works best for simple
> code segments while the 2 spaces indent feels better for more complex
> parts with a lot of hierarchy levels.
As I wrote above, if indentation leads to too long lines, it means that you have too nested for / while / if statements that need to be decomposed for maximal readability and understability.
> As long we do not stick to the 80 char line length I do not have any
> preference. In case we decide to respect the 80 char line length I do
> have a strong preference for using only 2 space intends.
>
> License Headers
>
> A short google search for "mvn plugin license" showed up several
> options for plugin that are able to manage license headers. I suggest
> to use one of those.
I'm sure Bertrand knows the best one to use :)
S.
--
Stefane Fermigier, Founder and Chairman, Nuxeo
Open Source, Java EE based, Enterprise Content Management (ECM)
http://www.nuxeo.com/ - +33 1 40 33 79 87 - http://twitter.com/sfermigier
Join the Nuxeo Group on LinkedIn: http://linkedin.com/groups?gid=43314
New Nuxeo release: http://nuxeo.com/dm54
"There's no such thing as can't. You always have a choice."
Re: [VOTE] code conventions for stanbol project
Posted by Rupert Westenthaler <rw...@apache.org>.
Hi all,
no vote yet, but let me add some comments:
Line length (section Sun code conventions 4.1)
I would suggest to exclude this point and allow longer lines than 80
chars. The argument about terminals is no longer valid nowadays and
with typical screen resolutions even lines with 150 chars do fit well.
Especially breaking up long log messages into several lines makes the
code much harder to read in my opinion.
Intend size
I have done some testing based on the suggested code formatter
configuration. In general the 4 spaces intend works best for simple
code segments while the 2 spaces indent feels better for more complex
parts with a lot of hierarchy levels.
As long we do not stick to the 80 char line length I do not have any
preference. In case we decide to respect the 80 char line length I do
have a strong preference for using only 2 space intends.
License Headers
A short google search for "mvn plugin license" showed up several
options for plugin that are able to manage license headers. I suggest
to use one of those.
best
Rupert Westenthaler
Re: [VOTE] code conventions for stanbol project
Posted by Fabian Christ <ch...@googlemail.com>.
+0
2010/12/12 Stefane Fermigier <sf...@nuxeo.com>:
> -1 for the 2 spaces / indent.
>
> S.
>
> On Dec 12, 2010, at 4:37 PM, Olivier Grisel wrote:
>
>> Hi all,
>>
>> I think we should adopt the same code conventions as other established
>> apache projects: Lucene, Solr and Mahout all use the Sun official code
>> conventions with the exception of using 2 spaces indents instead of 4.
>>
>> http://www.oracle.com/technetwork/java/codeconv-138413.html
>>
>> There is an eclipse code formatter (along with an unmaintained idea
>> version) here:
>>
>> https://cwiki.apache.org/confluence/display/MAHOUT/How+To+Contribute#HowToContribute-HelpfulResources
>>
>> The whole wiki page HowToContribute on Mahout's wiki is worth a read
>> too (many practical details on how to make and apply a patch for
>> instance):
>>
>> https://cwiki.apache.org/confluence/display/MAHOUT/How+To+Contribute
>>
>> The same formatters from the Apache Lucene / Solr projects are available
>> here:
>>
>> http://wiki.apache.org/solr/HowToContribute?action=AttachFile
>>
>> Note you are off-course free to use another editor / IDE, I just mention this
>> as a convenience for the majority of the developers that seam to use eclipse.
>>
>> Please vote with +1 / -1 in reply to this thread. If you are not a
>> project committer please add "(unbinding)" next to your vote.
>>
>> If those conventions are accepted I would like to do a batch reformat of the
>> existing stanbol codebase using this formatter next week.
>>
>> --
>> Olivier
>> http://twitter.com/ogrisel - http://github.com/ogrisel
>
> --
> Stefane Fermigier, Founder and Chairman, Nuxeo
> Open Source, Java EE based, Enterprise Content Management (ECM)
> http://www.nuxeo.com/ - +33 1 40 33 79 87 - http://twitter.com/sfermigier
> Join the Nuxeo Group on LinkedIn: http://linkedin.com/groups?gid=43314
> New Nuxeo release: http://nuxeo.com/dm54
> "There's no such thing as can't. You always have a choice."
>
>
--
Fabian
Re: [VOTE] code conventions for stanbol project
Posted by Stefane Fermigier <sf...@nuxeo.com>.
-1 for the 2 spaces / indent.
S.
On Dec 12, 2010, at 4:37 PM, Olivier Grisel wrote:
> Hi all,
>
> I think we should adopt the same code conventions as other established
> apache projects: Lucene, Solr and Mahout all use the Sun official code
> conventions with the exception of using 2 spaces indents instead of 4.
>
> http://www.oracle.com/technetwork/java/codeconv-138413.html
>
> There is an eclipse code formatter (along with an unmaintained idea
> version) here:
>
> https://cwiki.apache.org/confluence/display/MAHOUT/How+To+Contribute#HowToContribute-HelpfulResources
>
> The whole wiki page HowToContribute on Mahout's wiki is worth a read
> too (many practical details on how to make and apply a patch for
> instance):
>
> https://cwiki.apache.org/confluence/display/MAHOUT/How+To+Contribute
>
> The same formatters from the Apache Lucene / Solr projects are available
> here:
>
> http://wiki.apache.org/solr/HowToContribute?action=AttachFile
>
> Note you are off-course free to use another editor / IDE, I just mention this
> as a convenience for the majority of the developers that seam to use eclipse.
>
> Please vote with +1 / -1 in reply to this thread. If you are not a
> project committer please add "(unbinding)" next to your vote.
>
> If those conventions are accepted I would like to do a batch reformat of the
> existing stanbol codebase using this formatter next week.
>
> --
> Olivier
> http://twitter.com/ogrisel - http://github.com/ogrisel
--
Stefane Fermigier, Founder and Chairman, Nuxeo
Open Source, Java EE based, Enterprise Content Management (ECM)
http://www.nuxeo.com/ - +33 1 40 33 79 87 - http://twitter.com/sfermigier
Join the Nuxeo Group on LinkedIn: http://linkedin.com/groups?gid=43314
New Nuxeo release: http://nuxeo.com/dm54
"There's no such thing as can't. You always have a choice."
Re: [VOTE] code conventions for stanbol project
Posted by Tommaso Teofili <to...@gmail.com>.
+1
2010/12/12 Walter Kasper <ka...@dfki.de>
> +1
>
> --
> Dr. Walter Kasper
> DFKI GmbH
> Stuhlsatzenhausweg 3
> D-66123 Saarbrücken
> Tel.: +49-681-85775-5300 (*NEW NUMBER*)
> Fax: +49-681-85775-5338 (*NEW NUMBER*)
> Email: kasper@dfki.de
> -------------------------------------------------------------
> Deutsches Forschungszentrum fuer Kuenstliche Intelligenz GmbH
> Firmensitz: Trippstadter Strasse 122, D-67663 Kaiserslautern
>
> Geschaeftsfuehrung:
> Prof. Dr. Dr. h.c. mult. Wolfgang Wahlster (Vorsitzender)
> Dr. Walter Olthoff
>
> Vorsitzender des Aufsichtsrats:
> Prof. Dr. h.c. Hans A. Aukes
>
> Amtsgericht Kaiserslautern, HRB 2313
> -------------------------------------------------------------
>
>
Re: [VOTE] code conventions for stanbol project
Posted by Walter Kasper <ka...@dfki.de>.
+1
--
Dr. Walter Kasper
DFKI GmbH
Stuhlsatzenhausweg 3
D-66123 Saarbrücken
Tel.: +49-681-85775-5300 (*NEW NUMBER*)
Fax: +49-681-85775-5338 (*NEW NUMBER*)
Email: kasper@dfki.de
-------------------------------------------------------------
Deutsches Forschungszentrum fuer Kuenstliche Intelligenz GmbH
Firmensitz: Trippstadter Strasse 122, D-67663 Kaiserslautern
Geschaeftsfuehrung:
Prof. Dr. Dr. h.c. mult. Wolfgang Wahlster (Vorsitzender)
Dr. Walter Olthoff
Vorsitzender des Aufsichtsrats:
Prof. Dr. h.c. Hans A. Aukes
Amtsgericht Kaiserslautern, HRB 2313
-------------------------------------------------------------