You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@maven.apache.org by Vincent Siveton <vs...@apache.org> on 2008/07/03 23:00:15 UTC
[DISCUSS] Maven Team Conventions
Hi folks,
Following recent discussions on dev@ about POM style [1] and Jira
versioning [2], I created several documents about our code style and
conventions, jira and svn conventions.
http://svn.apache.org/repos/asf/maven/site/trunk/src/site/apt/developers/conventions
It is for discussions and all comments are welcome :)
Cheers,
Vincent
[1] http://www.nabble.com/-Proposal--Pom-Code-Style-(WAS-svn-commit%3A-r670264----maven-plugins-trunk-maven-site-plugin-pom.xml)-td18083228.html
[2] http://www.nabble.com/Re%3A--jira--Updated%3A-(MNG-3468)-FileSet-needs-a-toString()-method-to-properly-print-in-debug-mode-td18185825.html
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: [DISCUSS] Maven Team Conventions
Posted by Brett Porter <br...@apache.org>.
Thanks Benjamin, I agree with this.
On 05/07/2008, at 7:12 PM, Benjamin Bentmann wrote:
> Brett Porter wrote:
>
>> I disagree on JIRA issues - for making release notes and keeping
>> track I think it's best to have an issue whenever possible.
>
> Having detailed release notes is surely a good point since it's the
> easiest way for users to rate a new release in terms of benefits/
> risks when updating. But I guess something like "Improved javadoc"
> is not that interesting that it should popup in the release notes,
> i.e. Vincent's general distinction between "Minor changes" and
> "Larger changes" makes sense.
>
> However, I feel the statement
>
> jira.apt
> * <<Minor changes>>, like bug fixes
>
> is misleading. Of course there a "bug fixes" like correcting typos
> that can go in without jiras but in general I call a bug fix a major
> change that is going to impact users ("Jesus, they got that working,
> great!") ;-)
>
> Hence I propose the following update:
>
> * <<Minor changes>>, like code reformatting, documentation fixes,
> etc. that aren't going to impact other users can be committed
> without much issue.
>
> * <<Major changes>>, like bug fixes, API changes, significant
> refactoring, and pretty much any change of more than 100 lines,
> should have a JIRA ticket associated with it, or at least an email
> discussion.
>
>
> Benjamin
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
--
Brett Porter
brett@apache.org
http://blogs.exist.com/bporter/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: [DISCUSS] Maven Team Conventions
Posted by Benjamin Bentmann <be...@udo.edu>.
Brett Porter wrote:
> I disagree on JIRA issues - for making release notes and keeping track I
> think it's best to have an issue whenever possible.
Having detailed release notes is surely a good point since it's the
easiest way for users to rate a new release in terms of benefits/risks
when updating. But I guess something like "Improved javadoc" is not that
interesting that it should popup in the release notes, i.e. Vincent's
general distinction between "Minor changes" and "Larger changes" makes
sense.
However, I feel the statement
jira.apt
* <<Minor changes>>, like bug fixes
is misleading. Of course there a "bug fixes" like correcting typos that
can go in without jiras but in general I call a bug fix a major change
that is going to impact users ("Jesus, they got that working, great!") ;-)
Hence I propose the following update:
* <<Minor changes>>, like code reformatting, documentation fixes, etc.
that aren't going to impact other users can be committed without much issue.
* <<Major changes>>, like bug fixes, API changes, significant
refactoring, and pretty much any change of more than 100 lines, should
have a JIRA ticket associated with it, or at least an email discussion.
Benjamin
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: [DISCUSS] Maven Team Conventions
Posted by Vincent Siveton <vi...@gmail.com>.
Hi,
2008/7/5, Brett Porter <br...@apache.org>:
> Just a couple of comments...
>
> code.apt:
> ~~ * Using SVN properties like \$Id: \$ => Is it a wanted goal for all
> files like java or apt?
> I think this is helpful, though maybe optional. I don't really think it's
We can start to include it in all new files.
> good for the @version tag in Javadoc though.
Personally, I am in favour to use @version $Id:$ in javacode. The
important tag is @since.
> * <<Indentation>>: Always use 2 space indents and <<never>> use tabs!
> The two space rule is only for text files, right? We use 4 for Java in all
> indents, but the document doesn't indicate that.
Fixed
> * <<Readingness>>: Specify code grouping members, if needed. For instance
> in a Mojo class, you could have:
> I've found these are used inconsistently and get out of date. Like all
> comments, someone should add them if they think they'll help, but as a
> general rule I'd omit this.
>
Do we want to improves the readability of the code by sorting members?
If so, any recommended layout?
> jira.apt:
>
> I disagree on JIRA issues - for making release notes and keeping track I
> think it's best to have an issue whenever possible.
>
Other comments?
Cheers,
Vincent
> BTW, I posted some conventions to this list in the past, maybe we could
> incorporate them:
> http://markmail.org/message/wfv2lw66i2gggnaq
>
> Thanks,
> Brett
>
>
>
> On 04/07/2008, at 7:00 AM, Vincent Siveton wrote:
>
>
> >
> > Hi folks,
> >
> > Following recent discussions on dev@ about POM style [1] and Jira
> > versioning [2], I created several documents about our code style and
> > conventions, jira and svn conventions.
> >
> >
> http://svn.apache.org/repos/asf/maven/site/trunk/src/site/apt/developers/conventions
> >
> > It is for discussions and all comments are welcome :)
> >
> > Cheers,
> >
> > Vincent
> >
> > [1]
> http://www.nabble.com/-Proposal--Pom-Code-Style-(WAS-svn-commit%3A-r670264----maven-plugins-trunk-maven-site-plugin-pom.xml)-td18083228.html
> > [2]
> http://www.nabble.com/Re%3A--jira--Updated%3A-(MNG-3468)-FileSet-needs-a-toString()-method-to-properly-print-in-debug-mode-td18185825.html
> >
> >
> ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> > For additional commands, e-mail: dev-help@maven.apache.org
> >
> >
>
> --
> Brett Porter
> brett@apache.org
> http://blogs.exist.com/bporter/
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: [DISCUSS] Maven Team Conventions
Posted by Brett Porter <br...@apache.org>.
Just a couple of comments...
code.apt:
~~ * Using SVN properties like \$Id: \$ => Is it a wanted goal for all
files like java or apt?
I think this is helpful, though maybe optional. I don't really think
it's good for the @version tag in Javadoc though.
* <<Indentation>>: Always use 2 space indents and <<never>> use tabs!
The two space rule is only for text files, right? We use 4 for Java in
all indents, but the document doesn't indicate that.
* <<Readingness>>: Specify code grouping members, if needed. For
instance in a Mojo class, you could have:
I've found these are used inconsistently and get out of date. Like all
comments, someone should add them if they think they'll help, but as a
general rule I'd omit this.
jira.apt:
I disagree on JIRA issues - for making release notes and keeping track
I think it's best to have an issue whenever possible.
BTW, I posted some conventions to this list in the past, maybe we
could incorporate them: http://markmail.org/message/wfv2lw66i2gggnaq
Thanks,
Brett
On 04/07/2008, at 7:00 AM, Vincent Siveton wrote:
> Hi folks,
>
> Following recent discussions on dev@ about POM style [1] and Jira
> versioning [2], I created several documents about our code style and
> conventions, jira and svn conventions.
>
> http://svn.apache.org/repos/asf/maven/site/trunk/src/site/apt/developers/conventions
>
> It is for discussions and all comments are welcome :)
>
> Cheers,
>
> Vincent
>
> [1] http://www.nabble.com/-Proposal--Pom-Code-Style-(WAS-svn-commit%3A-r670264----maven-plugins-trunk-maven-site-plugin-pom.xml)-td18083228.html
> [2] http://www.nabble.com/Re%3A--jira--Updated%3A-(MNG-3468)-FileSet-needs-a-toString()-method-to-properly-print-in-debug-mode-td18185825.html
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
--
Brett Porter
brett@apache.org
http://blogs.exist.com/bporter/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: [DISCUSS] Maven Team Conventions
Posted by Paul Gier <pg...@redhat.com>.
Vincent Siveton wrote:
> Hi,
>
> 2008/7/5, Benjamin Bentmann <be...@udo.edu>:
>> Vincent Siveton wrote:
>>
>>
>> http://svn.apache.org/repos/asf/maven/site/trunk/src/site/apt/developers/conventions
>> code.apt
>> * <<Documentation>>: Document public interfaces well, i.e. all non-trivial
>> public and protected functions should include Javadoc that indicates what it
>> does.
>>
>> I would like to point out there are almost no methods that are really
>> non-trivial. In particular, getters and setters are not trivial.
>>
>> Take for instance getComponents() from the Plexus' ComponentSetDescriptor.
>> This method returns a null collection if no components have been added to
>> the list yet. The javadoc doesn't tell this "triviality" that can easily
>> cause NPEs in client code (MPLUGIN-114, MNG-2087). BTW, new
>> ComponentSetDescriptor().toString() also dies with a NPE.
>>
>> Concerning collections, other "trivial" aspects are whether to return
>> writable/unmodifiable live views or snapshots. For input parameters, will a
>> setter like setComponents() make a copy of the input collection or will
>> later changes to the supplied collection by the caller affect the
>> ComponentSetDescriptor?
>>
>
> I discourage the use of generated javadoc for getter/setter (not
> really useful). If some getter make some internal things, the javadoc
> is required.
>
>> Being open-source appears to support the habbit of omitting documentation
>> about member invariants and method pre-/postconditions. This in turn leaves
>> clients with the only choice of evaluating the current implementation to
>> derive the behavior. Then, nobody can tell what aspect of the behavior is
>> considered part of the API and what is just implementation-specific/buggy.
>
> Pre/post conditions are importants things IMHO, like could be null,
> could return null etc.
>
>> Just wondering what is more expensive or time consuming: Adding proper
>> documentation right from the start or fixing potential API misuses
>> afterwards?
>>
>
> Totally agree with you (concept of done in the agile way ;) )
>
> The main question is:
> Does the team want to refute any commits without proper javadoc?
>
I don't think we should reject commits that lack proper javadoc. Just let the
committer know where docs should be improved or document it yourself if you
notice something missing.
> Cheers,
>
> Vincent
>
>> Benjamin
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
>> For additional commands, e-mail: dev-help@maven.apache.org
>>
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: [DISCUSS] Maven Team Conventions
Posted by Vincent Siveton <vi...@gmail.com>.
Hi,
2008/7/5, Benjamin Bentmann <be...@udo.edu>:
> Vincent Siveton wrote:
>
>
> >
> http://svn.apache.org/repos/asf/maven/site/trunk/src/site/apt/developers/conventions
> >
>
> code.apt
> * <<Documentation>>: Document public interfaces well, i.e. all non-trivial
> public and protected functions should include Javadoc that indicates what it
> does.
>
> I would like to point out there are almost no methods that are really
> non-trivial. In particular, getters and setters are not trivial.
>
> Take for instance getComponents() from the Plexus' ComponentSetDescriptor.
> This method returns a null collection if no components have been added to
> the list yet. The javadoc doesn't tell this "triviality" that can easily
> cause NPEs in client code (MPLUGIN-114, MNG-2087). BTW, new
> ComponentSetDescriptor().toString() also dies with a NPE.
>
> Concerning collections, other "trivial" aspects are whether to return
> writable/unmodifiable live views or snapshots. For input parameters, will a
> setter like setComponents() make a copy of the input collection or will
> later changes to the supplied collection by the caller affect the
> ComponentSetDescriptor?
>
I discourage the use of generated javadoc for getter/setter (not
really useful). If some getter make some internal things, the javadoc
is required.
> Being open-source appears to support the habbit of omitting documentation
> about member invariants and method pre-/postconditions. This in turn leaves
> clients with the only choice of evaluating the current implementation to
> derive the behavior. Then, nobody can tell what aspect of the behavior is
> considered part of the API and what is just implementation-specific/buggy.
Pre/post conditions are importants things IMHO, like could be null,
could return null etc.
> Just wondering what is more expensive or time consuming: Adding proper
> documentation right from the start or fixing potential API misuses
> afterwards?
>
Totally agree with you (concept of done in the agile way ;) )
The main question is:
Does the team want to refute any commits without proper javadoc?
Cheers,
Vincent
>
> Benjamin
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: [DISCUSS] Maven Team Conventions
Posted by Benjamin Bentmann <be...@udo.edu>.
Vincent Siveton wrote:
> http://svn.apache.org/repos/asf/maven/site/trunk/src/site/apt/developers/conventions
code.apt
* <<Documentation>>: Document public interfaces well, i.e. all
non-trivial public and protected functions should include Javadoc that
indicates what it does.
I would like to point out there are almost no methods that are really
non-trivial. In particular, getters and setters are not trivial.
Take for instance getComponents() from the Plexus'
ComponentSetDescriptor. This method returns a null collection if no
components have been added to the list yet. The javadoc doesn't tell
this "triviality" that can easily cause NPEs in client code
(MPLUGIN-114, MNG-2087). BTW, new ComponentSetDescriptor().toString()
also dies with a NPE.
Concerning collections, other "trivial" aspects are whether to return
writable/unmodifiable live views or snapshots. For input parameters,
will a setter like setComponents() make a copy of the input collection
or will later changes to the supplied collection by the caller affect
the ComponentSetDescriptor?
Being open-source appears to support the habbit of omitting
documentation about member invariants and method pre-/postconditions.
This in turn leaves clients with the only choice of evaluating the
current implementation to derive the behavior. Then, nobody can tell
what aspect of the behavior is considered part of the API and what is
just implementation-specific/buggy.
Just wondering what is more expensive or time consuming: Adding proper
documentation right from the start or fixing potential API misuses
afterwards?
Benjamin
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org