You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Thomas Neidhart <th...@gmail.com> on 2012/08/30 20:57:30 UTC
[codec] javadoc style
Hi,
there are quite some differences on the javadoc style in the source
files, e.g. the number of spaces before a @param description, whether
there is an empty line between @param, @return and @throws.
Any thoughts on that? I am willing to clean up but do not want to impose
any personal preference.
btw. how do we treat the cases in the language.bm package wrt System.err
statements? For now I marked them as comment and put a FIXME.
The are there in case an unexpected input is read from a resource file
at runtime.
Thomas
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [codec] javadoc style
Posted by Gary Gregory <ga...@gmail.com>.
On Aug 30, 2012, at 18:22, Christian Hammers <ch...@lathspell.de> wrote:
> Am Thu, 30 Aug 2012 18:05:50 -0400
> schrieb Gary Gregory <ga...@gmail.com>:
>
>> On Aug 30, 2012, at 17:58, Christian Hammers <ch...@lathspell.de> wrote:
>>
>>> Am Thu, 30 Aug 2012 16:21:43 -0400
>>> schrieb Gary Gregory <ga...@gmail.com>:
>>>
>>>> On Thu, Aug 30, 2012 at 2:57 PM, Thomas Neidhart
>>>> <th...@gmail.com>wrote:
>>>>
>>>>> Hi,
>>>>>
>>>>> there are quite some differences on the javadoc style in the
>>>>> source files, e.g. the number of spaces before a @param
>>>>> description, whether there is an empty line between @param,
>>>>> @return and @throws.
>>>>>
>>>>
>>>> I like the default Eclipse formatting style:
>>>>
>>>> /**
>>>> * ...
>>>> *
>>>> * @param arg1
>>>> * blah blah blah blah
>>>> * @throws SomeException
>>>> * blah blah
>>>> */
>>>
>>> I usually stick with the default Netbeans formatting style which
>>> puts them on the same line. So does the example in the official
>>> Java Code Conventions (I only refer to it if it does things my way
>>> *g*) Doesn't waste so much precious vertical space either :)
>>>
>>> Anyway, what I wanted to ask was if there is maybe some kind of
>>> pom.xml magic that tells Eclipse, Netbeans, IDEA etc how we want
>>> the formatting so that we can all continue pressing ctrl-f for
>>> reformat before a commit and be sure that everything looks proper.
>>>
>>
>> There is such magic sadly. The best we can do is a combination of
>> convention and use of the checkstyle maven plugin.
>
> Hm, actually there seems to be some possibilities:
> For eclipse you can add <workspaceCodeStylesURL> to the eclipse plugin:
> http://maven.apache.org/plugins/maven-eclipse-plugin/examples/load-code-styles.html
> And for netbeans you can ship a nb-configuration.xml which is explicitly
> intended to be added to the version control system and be shared.
> Example:
> http://java.net/projects/electric/sources/svn/content/trunk/electric/electric-3d/nb-configuration.xml?rev=13769
>
> (In the meantime, please be generous if I submit a patch that contains
> a newline to much because auto-formatting added it :-))
One setting: line length 120.
Gary
>
> bye,
>
> -christian-
>
>
> ---------------------------------------------------------------------
> 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: [codec] javadoc style
Posted by Christian Hammers <ch...@lathspell.de>.
Am Thu, 30 Aug 2012 18:05:50 -0400
schrieb Gary Gregory <ga...@gmail.com>:
> On Aug 30, 2012, at 17:58, Christian Hammers <ch...@lathspell.de> wrote:
>
> > Am Thu, 30 Aug 2012 16:21:43 -0400
> > schrieb Gary Gregory <ga...@gmail.com>:
> >
> >> On Thu, Aug 30, 2012 at 2:57 PM, Thomas Neidhart
> >> <th...@gmail.com>wrote:
> >>
> >>> Hi,
> >>>
> >>> there are quite some differences on the javadoc style in the
> >>> source files, e.g. the number of spaces before a @param
> >>> description, whether there is an empty line between @param,
> >>> @return and @throws.
> >>>
> >>
> >> I like the default Eclipse formatting style:
> >>
> >> /**
> >> * ...
> >> *
> >> * @param arg1
> >> * blah blah blah blah
> >> * @throws SomeException
> >> * blah blah
> >> */
> >
> > I usually stick with the default Netbeans formatting style which
> > puts them on the same line. So does the example in the official
> > Java Code Conventions (I only refer to it if it does things my way
> > *g*) Doesn't waste so much precious vertical space either :)
> >
> > Anyway, what I wanted to ask was if there is maybe some kind of
> > pom.xml magic that tells Eclipse, Netbeans, IDEA etc how we want
> > the formatting so that we can all continue pressing ctrl-f for
> > reformat before a commit and be sure that everything looks proper.
> >
>
> There is such magic sadly. The best we can do is a combination of
> convention and use of the checkstyle maven plugin.
Hm, actually there seems to be some possibilities:
For eclipse you can add <workspaceCodeStylesURL> to the eclipse plugin:
http://maven.apache.org/plugins/maven-eclipse-plugin/examples/load-code-styles.html
And for netbeans you can ship a nb-configuration.xml which is explicitly
intended to be added to the version control system and be shared.
Example:
http://java.net/projects/electric/sources/svn/content/trunk/electric/electric-3d/nb-configuration.xml?rev=13769
(In the meantime, please be generous if I submit a patch that contains
a newline to much because auto-formatting added it :-))
bye,
-christian-
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [codec] javadoc style
Posted by Gary Gregory <ga...@gmail.com>.
On Aug 30, 2012, at 17:58, Christian Hammers <ch...@lathspell.de> wrote:
> Am Thu, 30 Aug 2012 16:21:43 -0400
> schrieb Gary Gregory <ga...@gmail.com>:
>
>> On Thu, Aug 30, 2012 at 2:57 PM, Thomas Neidhart
>> <th...@gmail.com>wrote:
>>
>>> Hi,
>>>
>>> there are quite some differences on the javadoc style in the source
>>> files, e.g. the number of spaces before a @param description,
>>> whether there is an empty line between @param, @return and @throws.
>>>
>>
>> I like the default Eclipse formatting style:
>>
>> /**
>> * ...
>> *
>> * @param arg1
>> * blah blah blah blah
>> * @throws SomeException
>> * blah blah
>> */
>
> I usually stick with the default Netbeans formatting style which puts
> them on the same line. So does the example in the official Java Code
> Conventions (I only refer to it if it does things my way *g*)
> Doesn't waste so much precious vertical space either :)
>
> Anyway, what I wanted to ask was if there is maybe some kind of pom.xml
> magic that tells Eclipse, Netbeans, IDEA etc how we want the formatting
> so that we can all continue pressing ctrl-f for reformat before a commit
> and be sure that everything looks proper.
>
There is such magic sadly. The best we can do is a combination of
convention and use of the checkstyle maven plugin.
We do not even have a common checkstyle configuration for commons.
Each component does what it wants.
I'd prefer a common guideline but aside from use spaces and not tabs
there is not much shared.
Ideally it would be nice to store in SVN format config for various
IDEs but that gets messy fast with many IDEs and IDE versions.
Gary
>
>>> btw. how do we treat the cases in the language.bm package wrt
>>> System.err statements? For now I marked them as comment and put a
>>> FIXME. The are there in case an unexpected input is read from a
>>> resource file at runtime.
>>>
>>
>> I would probably throw an IllegalArgumentException. You can code that
>> and see if the tests all pass.
>
> Using commons-logging and log.warn() would also be an options.
> More flexible if the use wants those warnings but of course also
> unexpected if no stdout is expected by this class. Is there a way
> to get Logger instance that is silent if not explicitly turned on?
>
> bye,
>
> -christian-
>
> ---------------------------------------------------------------------
> 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: [codec] javadoc style
Posted by Christian Hammers <ch...@lathspell.de>.
Am Thu, 30 Aug 2012 16:21:43 -0400
schrieb Gary Gregory <ga...@gmail.com>:
> On Thu, Aug 30, 2012 at 2:57 PM, Thomas Neidhart
> <th...@gmail.com>wrote:
>
> > Hi,
> >
> > there are quite some differences on the javadoc style in the source
> > files, e.g. the number of spaces before a @param description,
> > whether there is an empty line between @param, @return and @throws.
> >
>
> I like the default Eclipse formatting style:
>
> /**
> * ...
> *
> * @param arg1
> * blah blah blah blah
> * @throws SomeException
> * blah blah
> */
I usually stick with the default Netbeans formatting style which puts
them on the same line. So does the example in the official Java Code
Conventions (I only refer to it if it does things my way *g*)
Doesn't waste so much precious vertical space either :)
Anyway, what I wanted to ask was if there is maybe some kind of pom.xml
magic that tells Eclipse, Netbeans, IDEA etc how we want the formatting
so that we can all continue pressing ctrl-f for reformat before a commit
and be sure that everything looks proper.
> > btw. how do we treat the cases in the language.bm package wrt
> > System.err statements? For now I marked them as comment and put a
> > FIXME. The are there in case an unexpected input is read from a
> > resource file at runtime.
> >
>
> I would probably throw an IllegalArgumentException. You can code that
> and see if the tests all pass.
Using commons-logging and log.warn() would also be an options.
More flexible if the use wants those warnings but of course also
unexpected if no stdout is expected by this class. Is there a way
to get Logger instance that is silent if not explicitly turned on?
bye,
-christian-
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [codec] javadoc style
Posted by Gary Gregory <ga...@gmail.com>.
On Thu, Aug 30, 2012 at 2:57 PM, Thomas Neidhart
<th...@gmail.com>wrote:
> Hi,
>
> there are quite some differences on the javadoc style in the source
> files, e.g. the number of spaces before a @param description, whether
> there is an empty line between @param, @return and @throws.
>
I like the default Eclipse formatting style:
/**
* ...
*
* @param arg1
* blah blah blah blah
* @throws SomeException
* blah blah
*/
> Any thoughts on that? I am willing to clean up but do not want to impose
> any personal preference.
>
I'm not sure it is worth fixing, but if it bothers you, feel free :)
>
> btw. how do we treat the cases in the language.bm package wrt System.err
> statements? For now I marked them as comment and put a FIXME.
> The are there in case an unexpected input is read from a resource file
> at runtime.
>
I would probably throw an IllegalArgumentException. You can code that and
see if the tests all pass.
Gary
>
> Thomas
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
--
E-Mail: garydgregory@gmail.com | ggregory@apache.org
JUnit in Action, 2nd Ed: <http://goog_1249600977>http://bit.ly/ECvg0
Spring Batch in Action: <http://s.apache.org/HOq>http://bit.ly/bqpbCK
Blog: http://garygregory.wordpress.com
Home: http://garygregory.com/
Tweet! http://twitter.com/GaryGregory