You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@opennlp.apache.org by Jörn Kottmann <ko...@gmail.com> on 2011/11/19 16:55:06 UTC
Code Conventions
Hi all,
I added a code conventions page to our website:
http://opennlp.staging.apache.org/opennlp/code-conventions.html
Please have a look and comment.
Jörn
Re: Code Conventions
Posted by Alec Taylor <al...@gmail.com>.
On Sun, Nov 20, 2011 at 10:02 PM, Aliaksandr Autayeu
<al...@autayeu.com> wrote:
> This plugin connects Eclipse code formatter to IDEA. It is not a conversion
> of formatting settings, nor does it converts the settings. I had to get
> Eclipse, set up OpenNLP project there, import .xml file with settings from
> the site, then point the plugin to settings. Not a big deal for me, but may
> be a deal-breaker for somebody. The advantage is 100% compliance with
> project code formatting rules.
>
> By the way, the example on the page should be changed to have "catch" on
> the same line with the closing bracket ;)
>
> from this:
>
> } catch(NumberFormatException e) {
>
> to this:
>
> } catch(NumberFormatException e) {
They're the same!!!
>
> It's easy to test this - import the OpenNLP-Eclipse-Formatter.xml settings
> from the site into Eclipse, copy-paste the example, format, see :)
>
> Also, existing code base does not conform to this standard :) And, although
> I would add bracket forcing for "for" and "if" and others similar
> statements to the current code formatting standard (as a safety measure I
> explained earlier) before reformatting anything, the best example of even
> the current code format would be a formatted code base itself. And yes, a
> check-in hook to be sure it remains so :)
>
> Aliaksandr
>
> On Sun, Nov 20, 2011 at 1:11 AM, Jörn Kottmann <ko...@gmail.com> wrote:
>
>> On 11/20/11 12:50 AM, Aliaksandr Autayeu wrote:
>>
>>> The solution for IDEA is this plugin:
>>> http://plugins.intellij.net/**plugin/?idea&id=6546<http://plugins.intellij.net/plugin/?idea&id=6546>, which allows using
>>> Eclipse code formatter with OpenNLP formatting settings. I'm trying it now
>>> and it seems to work.
>>>
>>>
>>>
>> Is it possible to export it for IDEA? Otherwise we should add this link
>> to the page.
>>
>> Jörn
>>
Re: Code Conventions
Posted by Jörn Kottmann <ko...@gmail.com>.
On 11/20/11 4:22 PM, Alec Taylor wrote:
> I would recommend doing that using the astyle binary.
>
>
> Also for Eclipse, just use an Astyle wrapper, i.e.:
> http://astyleclipse.sourceforge.net/
In our current solution maven can download
and configure the formatter file for you in eclipse
with mvn eclipse:eclipse.
When we are using astyle the one-time-setup is
requires more steps.
Anyway we could just provide an additional astyle file.
Jörn
Re: Code Conventions
Posted by Alec Taylor <al...@gmail.com>.
I would recommend doing that using the astyle binary.
Also for Eclipse, just use an Astyle wrapper, i.e.:
http://astyleclipse.sourceforge.net/
Re: Code Conventions
Posted by Jörn Kottmann <ko...@gmail.com>.
On 11/20/11 4:01 PM, Aliaksandr Autayeu wrote:
>> > I am actually not to fond of reformatting the entire existing code base,
>> > since
>> > that makes things difficult to diff and changes often don't even improve
>> > the readability.
>> >
> Notice I didn't propose that. Exactly because I knew the answer in advance
> :)
Would you prefer to reformat the entire code base once?
Jörn
Re: Code Conventions
Posted by Jörn Kottmann <ko...@gmail.com>.
On 11/20/11 4:01 PM, Aliaksandr Autayeu wrote:
>> In our code base the catch is usually on the next line, we should change
>> > the
>> > eclipse formatter to do that.
> :(
We could leave this also open, then people can write as they
want.
Jörn
Re: Code Conventions
Posted by Aliaksandr Autayeu <al...@autayeu.com>.
>
> In our code base the catch is usually on the next line, we should change
> the
> eclipse formatter to do that.
:(
Also, existing code base does not conform to this standard:) And, although
>> I would add bracket forcing for "for" and "if" and others similar
>> statements to the current code formatting standard (as a safety measure I
>> explained earlier) before reformatting anything, the best example of even
>> the current code format would be a formatted code base itself. And yes, a
>> check-in hook to be sure it remains so:)
>>
>
> I am actually not to fond of reformatting the entire existing code base,
> since
> that makes things difficult to diff and changes often don't even improve
> the readability.
>
Notice I didn't propose that. Exactly because I knew the answer in advance
:)
Aliaksandr
Re: Code Conventions
Posted by Jörn Kottmann <ko...@gmail.com>.
On 11/20/11 12:02 PM, Aliaksandr Autayeu wrote:
> By the way, the example on the page should be changed to have "catch" on
> the same line with the closing bracket;)
>
> from this:
>
> } catch(NumberFormatException e) {
>
> to this:
>
> } catch(NumberFormatException e) {
>
> It's easy to test this - import the OpenNLP-Eclipse-Formatter.xml settings
> from the site into Eclipse, copy-paste the example, format, see:)
In our code base the catch is usually on the next line, we should change the
eclipse formatter to do that.
> Also, existing code base does not conform to this standard:) And, although
> I would add bracket forcing for "for" and "if" and others similar
> statements to the current code formatting standard (as a safety measure I
> explained earlier) before reformatting anything, the best example of even
> the current code format would be a formatted code base itself. And yes, a
> check-in hook to be sure it remains so:)
I am actually not to fond of reformatting the entire existing code base,
since
that makes things difficult to diff and changes often don't even improve
the readability.
For example when lines are reformatted which are not long enough.
Just give it a try in a class like BeamSearch.
We should add the one with the brackets in if and for statements.
Jörn
Re: Code Conventions
Posted by Aliaksandr Autayeu <al...@autayeu.com>.
> Can't you configure every IDE to notice if the if statement is not
> within braces?
>
> (you can also configure emacs and vim to notice)
>
> I find that if your coder can't even notice when his conditional or
> loop is greater than 2 lines and thus requires braces, then that coder
> isn't any good.
>
To err is human. If there is a safety thing which frees your mind of minute
details, and always guarantees right behaviour, why not use it? Think, may
be 10 years down the road you'll change your mind. And while you're right
about "coder", I would remind that there aren't only coders here, there are
researchers as well.
I would agree with Jörn:
- encourage format style, not force it, if code is already readable
- avoid reformatting existing code base, but gradually move it to a
standard, that is, format new code and refactored one.
- encourage safe programming practices and format style, like brackets, in
the new code
Aliaksandr
Re: Code Conventions
Posted by Alec Taylor <al...@gmail.com>.
Great.
Well there are some astyle options
(http://astyle.sourceforge.net/astyle.html#_Padding_Options) for
configuring this kind of padding, also:
--break-closing-brackets OR -y
Break brackets before closing headers (e.g. 'else', 'catch', ...).
Use with --brackets=attach, --brackets=linux,
or --brackets=stroustrup.
--break-elseifs OR -e
Break 'else if()' statements into two different lines.
--add-brackets OR -j
Add brackets to unbracketed one line conditional statements.
--add-one-line-brackets OR -J
Add one line brackets to unbracketed one line conditional
statements.
--keep-one-line-blocks OR -O
Don't break blocks residing completely on one line.
--keep-one-line-statements OR -o
Don't break lines containing multiple statements into
multiple single-statement lines.
On Mon, Nov 21, 2011 at 9:25 PM, Jörn Kottmann <ko...@gmail.com> wrote:
> On 11/21/11 10:59 AM, Alec Taylor wrote:
>>
>> Can't you configure every IDE to notice if the if statement is not
>> within braces?
>>
>> (you can also configure emacs and vim to notice)
>
>
> Didn't see that option in eclipse, but I wouldn't use it anyway,
> since it will then output tons of warnings for existing code and
> I don't think that this violation would be a reason to change our
> existing code.
>
>> I find that if your coder can't even notice when his conditional or
>> loop is greater than 2 lines and thus requires braces, then that coder
>> isn't any good.
>
>
> If someone new starts to write or change our code they usually try
> to imitate our existing coding style. The code conventions page should
> be a help to make this easier.
>
> The people which belong the group above will always produce code which
> is readable and can be committed in the format it is anyway.
> I personally don't want to strictly enforce code conventions on code which
> has a good readability and mostly complies with the code conventions.
>
> Jörn
>
>
Re: Code Conventions
Posted by Jörn Kottmann <ko...@gmail.com>.
On 11/21/11 10:59 AM, Alec Taylor wrote:
> Can't you configure every IDE to notice if the if statement is not
> within braces?
>
> (you can also configure emacs and vim to notice)
Didn't see that option in eclipse, but I wouldn't use it anyway,
since it will then output tons of warnings for existing code and
I don't think that this violation would be a reason to change our
existing code.
> I find that if your coder can't even notice when his conditional or
> loop is greater than 2 lines and thus requires braces, then that coder
> isn't any good.
If someone new starts to write or change our code they usually try
to imitate our existing coding style. The code conventions page should
be a help to make this easier.
The people which belong the group above will always produce code which
is readable and can be committed in the format it is anyway.
I personally don't want to strictly enforce code conventions on code which
has a good readability and mostly complies with the code conventions.
Jörn
Re: Code Conventions
Posted by Alec Taylor <al...@gmail.com>.
Can't you configure every IDE to notice if the if statement is not
within braces?
(you can also configure emacs and vim to notice)
I find that if your coder can't even notice when his conditional or
loop is greater than 2 lines and thus requires braces, then that coder
isn't any good.
On Mon, Nov 21, 2011 at 8:52 PM, Jörn Kottmann <ko...@gmail.com> wrote:
> On 11/21/11 10:36 AM, Alec Taylor wrote:
>>
>> Pfft, I much prefer (for readability) the non-brace version where
>> possible.
>>
>> Lets set our own standard, rather than follow someone elses.
>>
>> Actually, this project is incubator. Do apache require a certain standard?
>
>
> At Apache we need to follow the "Apache way", but that is mostly about
> project management, legal requirements and other things.
>
> Apache leaves all project related decisions to the project team.
> Therefore we are free to decide which code conventions we want to
> follow, or even if we want to follow some.
>
> Back to the if with or without braces. In the current code base it is mixed.
> The argument not to use the if without braces is that they are more error
> prone,
> because you can accidentally believe that a statement is inside the if which
> is not.
>
> Jörn
Re: Code Conventions
Posted by Jörn Kottmann <ko...@gmail.com>.
On 11/21/11 10:36 AM, Alec Taylor wrote:
> Pfft, I much prefer (for readability) the non-brace version where possible.
>
> Lets set our own standard, rather than follow someone elses.
>
> Actually, this project is incubator. Do apache require a certain standard?
At Apache we need to follow the "Apache way", but that is mostly about
project management, legal requirements and other things.
Apache leaves all project related decisions to the project team.
Therefore we are free to decide which code conventions we want to
follow, or even if we want to follow some.
Back to the if with or without braces. In the current code base it is mixed.
The argument not to use the if without braces is that they are more
error prone,
because you can accidentally believe that a statement is inside the if
which is not.
Jörn
Re: Code Conventions
Posted by Alec Taylor <al...@gmail.com>.
Pfft, I much prefer (for readability) the non-brace version where possible.
Lets set our own standard, rather than follow someone elses.
Actually, this project is incubator. Do apache require a certain standard?
On Mon, Nov 21, 2011 at 8:25 PM, Jörn Kottmann <ko...@gmail.com> wrote:
> On 11/20/11 12:02 PM, Aliaksandr Autayeu wrote:
>>
>> And, although
>> I would add bracket forcing for "for" and "if" and others similar
>> statements to the current code formatting standard (as a safety measure I
>> explained earlier) before reformatting anything, the best example of even
>> the current code format would be a formatted code base itself.
>
>
> This is part of the Sun code conventions to which we made a few
> exceptions. So we don't need to list this as an exception.
>
> Have a look here:
> http://www.oracle.com/technetwork/java/codeconventions-142311.html#431
>
> "Note: if statements always use braces {}. Avoid the following error-prone
> form: "
>
> Jörn
Re: Code Conventions
Posted by Jörn Kottmann <ko...@gmail.com>.
On 11/20/11 12:02 PM, Aliaksandr Autayeu wrote:
> And, although
> I would add bracket forcing for "for" and "if" and others similar
> statements to the current code formatting standard (as a safety measure I
> explained earlier) before reformatting anything, the best example of even
> the current code format would be a formatted code base itself.
This is part of the Sun code conventions to which we made a few
exceptions. So we don't need to list this as an exception.
Have a look here:
http://www.oracle.com/technetwork/java/codeconventions-142311.html#431
"Note: if statements always use braces {}. Avoid the following
error-prone form: "
Jörn
Re: Code Conventions
Posted by Aliaksandr Autayeu <al...@autayeu.com>.
This plugin connects Eclipse code formatter to IDEA. It is not a conversion
of formatting settings, nor does it converts the settings. I had to get
Eclipse, set up OpenNLP project there, import .xml file with settings from
the site, then point the plugin to settings. Not a big deal for me, but may
be a deal-breaker for somebody. The advantage is 100% compliance with
project code formatting rules.
By the way, the example on the page should be changed to have "catch" on
the same line with the closing bracket ;)
from this:
} catch(NumberFormatException e) {
to this:
} catch(NumberFormatException e) {
It's easy to test this - import the OpenNLP-Eclipse-Formatter.xml settings
from the site into Eclipse, copy-paste the example, format, see :)
Also, existing code base does not conform to this standard :) And, although
I would add bracket forcing for "for" and "if" and others similar
statements to the current code formatting standard (as a safety measure I
explained earlier) before reformatting anything, the best example of even
the current code format would be a formatted code base itself. And yes, a
check-in hook to be sure it remains so :)
Aliaksandr
On Sun, Nov 20, 2011 at 1:11 AM, Jörn Kottmann <ko...@gmail.com> wrote:
> On 11/20/11 12:50 AM, Aliaksandr Autayeu wrote:
>
>> The solution for IDEA is this plugin:
>> http://plugins.intellij.net/**plugin/?idea&id=6546<http://plugins.intellij.net/plugin/?idea&id=6546>, which allows using
>> Eclipse code formatter with OpenNLP formatting settings. I'm trying it now
>> and it seems to work.
>>
>>
>>
> Is it possible to export it for IDEA? Otherwise we should add this link
> to the page.
>
> Jörn
>
Re: Code Conventions
Posted by Jörn Kottmann <ko...@gmail.com>.
On 11/20/11 12:50 AM, Aliaksandr Autayeu wrote:
> The solution for IDEA is this plugin:
> http://plugins.intellij.net/plugin/?idea&id=6546 , which allows using
> Eclipse code formatter with OpenNLP formatting settings. I'm trying it now
> and it seems to work.
>
>
Is it possible to export it for IDEA? Otherwise we should add this link
to the page.
Jörn
Re: Code Conventions
Posted by Aliaksandr Autayeu <al...@autayeu.com>.
The solution for IDEA is this plugin:
http://plugins.intellij.net/plugin/?idea&id=6546 , which allows using
Eclipse code formatter with OpenNLP formatting settings. I'm trying it now
and it seems to work.
Aliaksandr
On Sat, Nov 19, 2011 at 5:20 PM, Jörn Kottmann <ko...@gmail.com> wrote:
> On 11/19/11 5:10 PM, Alec Taylor wrote:
>
>> How about giving people an astyle command to run as well, could also
>> be used to update all files with whatever convention you want:
>>
>> i.e. I use:
>> astyle -A2T4CSKNOo
>>
>>
> We have a format file for eclipse already, and more style files are
> welcome.
> Do you want to contribute one for astyle?
>
> The eclipse one should be linked from that page, I will add it.
>
> Jörn
>
Re: Code Conventions
Posted by Jörn Kottmann <ko...@gmail.com>.
On 11/19/11 5:10 PM, Alec Taylor wrote:
> How about giving people an astyle command to run as well, could also
> be used to update all files with whatever convention you want:
>
> i.e. I use:
> astyle -A2T4CSKNOo
>
We have a format file for eclipse already, and more style files are welcome.
Do you want to contribute one for astyle?
The eclipse one should be linked from that page, I will add it.
Jörn
Re: Code Conventions
Posted by Alec Taylor <al...@gmail.com>.
How about giving people an astyle command to run as well, could also
be used to update all files with whatever convention you want:
i.e. I use:
astyle -A2T4CSKNOo
On Sun, Nov 20, 2011 at 2:55 AM, Jörn Kottmann <ko...@gmail.com> wrote:
> Hi all,
>
> I added a code conventions page to our website:
> http://opennlp.staging.apache.org/opennlp/code-conventions.html
>
> Please have a look and comment.
>
> Jörn