You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@hc.apache.org by Tony Poppleton <to...@wanadoo.fr> on 2010/01/15 03:29:03 UTC
Code formatting and standards
(this was previously posted on the users mailing list by mistake, reposting to the correct channel...)
Hi,
I use the Eclipse IDE for all my development, and one useful feature is the code formatter to ensure standardization. Does anyone have a premade Eclipse IDE formatter for HttpCore/HttpClient that they could send me please?
Is code formatting enforced in these projects?
On a related topic, is there a coding standards document, for example on the usage of the "final" keyword, to ensure coding is consistent between developers?
Many thanks,
Tony
Re: Code formatting and standards
Posted by Tony Poppleton <to...@wanadoo.fr>.
Hi,
Thanks for the feedback, I have updated the page with your suggestions.
Tony
> Message du 16/01/10 17:57
> De : "sebb"
> A : "HttpComponents Project"
> Copie à :
> Objet : Re: Code formatting and standards
>
>
> On 16/01/2010, Oleg Kalnichevski wrote:
> > Tony Poppleton wrote:
> >
> > > Hi Sebb,
> > >
> > > As requested, I have produced a first stab at some coding conventions at
> > http://wiki.apache.org/HttpComponents/CodingConventions
> > >
> > > Please feel free to modify as you see fit. There is still some work to be
> > done, most notably for me adding the Eclipse code formatting (if there is no
> > objection then I will add the ones Oleg sent earlier, until the appropriate
> > body comes up with the official one)
> > >
> > > On your point about being consistent in a file being more important than
> > across the project, I would disagree. If these conventions (and the code
> > formatter) become the official project standards, then they are exactly
> > that, and all files in the project should adhere to them by definition.
> > After the single SVN commit to clean up all the code, then both file and
> > project consistency will be maintained forevermore.
>
> My point was about applying patches to existing code, which might not
> yet have been homogenised.
>
> > >
> > > Regards,
> > > Tony
> > >
> > >
> >
> > (1) I think it would be worth dividing content of the document into two
> > distinct sections: requirements and recommendations. A failure to comply
> > with the requirements may lead to the rejection of a patch.
>
> I'd prefer to see the items flagged with MUST and SHOULD; makes it
> easier to keep related items together (and easier to change the
> priority!) IIRC this is the way RFCs do it.
>
> > (2) Can we tone down this particular line a little ;-) "Prefer unchecked
> > exceptions (like RuntimeException) over checked exceptions". I personally
> > would be much more content with something like "checked exceptions should
> > represent potentially recoverable exceptions; runtime exceptions should
> > represent non-recoverable errors / unexpected errors / programming errors"
> > or some such.
>
> +1
>
> > Oleg
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
> > For additional commands, e-mail: dev-help@hc.apache.org
> >
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
> For additional commands, e-mail: dev-help@hc.apache.org
>
> ---------------------------------------------------------------------------------------
> Orange vous informe que cet e-mail a ete controle par l'anti-virus mail.
> Aucun virus connu a ce jour par nos services n'a ete detecte.
>
>
>
Re: Code formatting and standards
Posted by sebb <se...@gmail.com>.
On 16/01/2010, Oleg Kalnichevski <ol...@apache.org> wrote:
> Tony Poppleton wrote:
>
> > Hi Sebb,
> >
> > As requested, I have produced a first stab at some coding conventions at
> http://wiki.apache.org/HttpComponents/CodingConventions
> >
> > Please feel free to modify as you see fit. There is still some work to be
> done, most notably for me adding the Eclipse code formatting (if there is no
> objection then I will add the ones Oleg sent earlier, until the appropriate
> body comes up with the official one)
> >
> > On your point about being consistent in a file being more important than
> across the project, I would disagree. If these conventions (and the code
> formatter) become the official project standards, then they are exactly
> that, and all files in the project should adhere to them by definition.
> After the single SVN commit to clean up all the code, then both file and
> project consistency will be maintained forevermore.
My point was about applying patches to existing code, which might not
yet have been homogenised.
> >
> > Regards,
> > Tony
> >
> >
>
> (1) I think it would be worth dividing content of the document into two
> distinct sections: requirements and recommendations. A failure to comply
> with the requirements may lead to the rejection of a patch.
I'd prefer to see the items flagged with MUST and SHOULD; makes it
easier to keep related items together (and easier to change the
priority!) IIRC this is the way RFCs do it.
> (2) Can we tone down this particular line a little ;-) "Prefer unchecked
> exceptions (like RuntimeException) over checked exceptions". I personally
> would be much more content with something like "checked exceptions should
> represent potentially recoverable exceptions; runtime exceptions should
> represent non-recoverable errors / unexpected errors / programming errors"
> or some such.
+1
> Oleg
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
> For additional commands, e-mail: dev-help@hc.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: Code formatting and standards
Posted by Oleg Kalnichevski <ol...@apache.org>.
Tony Poppleton wrote:
> Hi Sebb,
>
> As requested, I have produced a first stab at some coding conventions at http://wiki.apache.org/HttpComponents/CodingConventions
>
> Please feel free to modify as you see fit. There is still some work to be done, most notably for me adding the Eclipse code formatting (if there is no objection then I will add the ones Oleg sent earlier, until the appropriate body comes up with the official one)
>
> On your point about being consistent in a file being more important than across the project, I would disagree. If these conventions (and the code formatter) become the official project standards, then they are exactly that, and all files in the project should adhere to them by definition. After the single SVN commit to clean up all the code, then both file and project consistency will be maintained forevermore.
>
> Regards,
> Tony
>
(1) I think it would be worth dividing content of the document into two
distinct sections: requirements and recommendations. A failure to comply
with the requirements may lead to the rejection of a patch.
(2) Can we tone down this particular line a little ;-) "Prefer unchecked
exceptions (like RuntimeException) over checked exceptions". I
personally would be much more content with something like "checked
exceptions should represent potentially recoverable exceptions; runtime
exceptions should represent non-recoverable errors / unexpected errors /
programming errors" or some such.
Oleg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: Code formatting and standards
Posted by Tony Poppleton <to...@wanadoo.fr>.
Hi Sebb,
As requested, I have produced a first stab at some coding conventions at http://wiki.apache.org/HttpComponents/CodingConventions
Please feel free to modify as you see fit. There is still some work to be done, most notably for me adding the Eclipse code formatting (if there is no objection then I will add the ones Oleg sent earlier, until the appropriate body comes up with the official one)
On your point about being consistent in a file being more important than across the project, I would disagree. If these conventions (and the code formatter) become the official project standards, then they are exactly that, and all files in the project should adhere to them by definition. After the single SVN commit to clean up all the code, then both file and project consistency will be maintained forevermore.
Regards,
Tony
> Message du 15/01/10 14:12
> De : "sebb"
> A : "HttpComponents Project" , "Tony Poppleton"
> Copie à :
> Objet : Re: Code formatting and standards
>
>
> On 15/01/2010, Tony Poppleton wrote:
> > Thanks Oleg.
> >
> > I would certainly encourage you to try again at enforcing both code formatting and coding standards. The top committers on this project should get together, come up with something they agree on, and then simply enforce it on everyone else.
>
> The PMC (who may or may not be "top committers", or even commit to the
> HC codebase) are the only group who can make such decisions.
>
> Given that the PMC may change over time, the standards may also change
> over time.
>
> However, I agree that it would be sensible to look at producing some
> coding recommendations, as those should help new contributors.
>
> Why don't you start a Wiki page with your suggestions?
> Or perhaps two, one for formatting, and another for coding (final vars etc)
>
> > The Eclipse code formatter settings should be made available on the website, as well as the "Clean Up" settings. Eclipse can be used to apply the settings on the whole project, so you can commit one revision where every class will adhere to the new standards.
>
> That's rather drastic.
>
> As far as code layout is concerned, I take the view that changes to
> existing code should generally adhere to whatever scheme that file
> currently uses. Consistency within a file is more important than
> consistency across all files.
>
> > Thanks,
> > Tony
> >
> > > Message du 15/01/10 11:59
> > > De : "Oleg Kalnichevski"
> > > A : "Tony Poppleton"
> > > Copie à : dev@hc.apache.org
> > > Objet : Re: Code formatting and standards
> >
> > >
> > > On Fri, 2010-01-15 at 03:29 +0100, Tony Poppleton wrote:
> > > > (this was previously posted on the users mailing list by mistake, reposting to the correct channel...)
> > > >
> > > > Hi,
> > > >
> > > > I use the Eclipse IDE for all my development, and one useful feature is the code formatter to ensure standardization. Does anyone have a premade Eclipse IDE formatter for HttpCore/HttpClient that they could send me please?
> > > >
> > >
> > > Hi Tony
> > >
> > > Here is the file containing code formatting settings that I use.
> > >
> > >
> > > > Is code formatting enforced in these projects?
> > > >
> > >
> > > No, not really. The only hard requirement is the use of spaces instead
> > > of tabs and indentation with 4 spaces.
> > >
> > >
> > > > On a related topic, is there a coding standards document, for example on the usage of the "final" keyword, to ensure coding is consistent between developers?
> > > >
> > >
> > > Historically there used to be too many developers with completely
> > > different tastes for the code formatting standards, so any attempt at
> > > coming up with a common policy could easily escalate into a full scale
> > > 'food fight'. I personally have fairly bizarre preferences for code
> > > formatting and therefore do not find it possible to impose them onto
> > > other fellow human beings.
> > >
> > > We could try, though, given the fact that the code base is becoming
> > > stable and major cross cutting changes are unlikely.
> > >
> > > Oleg
> > >
> > > > Many thanks,
> > > > Tony
> > >
> > >
> >
> > > ---------------------------------------------------------------------------------------
> >
> > > Orange vous informe que cet e-mail a ete controle par l'anti-virus mail.
> > > Aucun virus connu a ce jour par nos services n'a ete detecte.
> > >
> > >
> >
> > > [ (pas de nom de fichier) (0.2 Ko) ]
> > > [ oleg's (28.3 Ko) ]
> ---------------------------------------------------------------------------------------
> Orange vous informe que cet e-mail a ete controle par l'anti-virus mail.
> Aucun virus connu a ce jour par nos services n'a ete detecte.
>
>
>
Re: Code formatting and standards
Posted by sebb <se...@gmail.com>.
On 15/01/2010, Tony Poppleton <to...@wanadoo.fr> wrote:
> Thanks Oleg.
>
> I would certainly encourage you to try again at enforcing both code formatting and coding standards. The top committers on this project should get together, come up with something they agree on, and then simply enforce it on everyone else.
The PMC (who may or may not be "top committers", or even commit to the
HC codebase) are the only group who can make such decisions.
Given that the PMC may change over time, the standards may also change
over time.
However, I agree that it would be sensible to look at producing some
coding recommendations, as those should help new contributors.
Why don't you start a Wiki page with your suggestions?
Or perhaps two, one for formatting, and another for coding (final vars etc)
> The Eclipse code formatter settings should be made available on the website, as well as the "Clean Up" settings. Eclipse can be used to apply the settings on the whole project, so you can commit one revision where every class will adhere to the new standards.
That's rather drastic.
As far as code layout is concerned, I take the view that changes to
existing code should generally adhere to whatever scheme that file
currently uses. Consistency within a file is more important than
consistency across all files.
> Thanks,
> Tony
>
> > Message du 15/01/10 11:59
> > De : "Oleg Kalnichevski"
> > A : "Tony Poppleton"
> > Copie à : dev@hc.apache.org
> > Objet : Re: Code formatting and standards
>
> >
> > On Fri, 2010-01-15 at 03:29 +0100, Tony Poppleton wrote:
> > > (this was previously posted on the users mailing list by mistake, reposting to the correct channel...)
> > >
> > > Hi,
> > >
> > > I use the Eclipse IDE for all my development, and one useful feature is the code formatter to ensure standardization. Does anyone have a premade Eclipse IDE formatter for HttpCore/HttpClient that they could send me please?
> > >
> >
> > Hi Tony
> >
> > Here is the file containing code formatting settings that I use.
> >
> >
> > > Is code formatting enforced in these projects?
> > >
> >
> > No, not really. The only hard requirement is the use of spaces instead
> > of tabs and indentation with 4 spaces.
> >
> >
> > > On a related topic, is there a coding standards document, for example on the usage of the "final" keyword, to ensure coding is consistent between developers?
> > >
> >
> > Historically there used to be too many developers with completely
> > different tastes for the code formatting standards, so any attempt at
> > coming up with a common policy could easily escalate into a full scale
> > 'food fight'. I personally have fairly bizarre preferences for code
> > formatting and therefore do not find it possible to impose them onto
> > other fellow human beings.
> >
> > We could try, though, given the fact that the code base is becoming
> > stable and major cross cutting changes are unlikely.
> >
> > Oleg
> >
> > > Many thanks,
> > > Tony
> >
> >
>
> > ---------------------------------------------------------------------------------------
>
> > Orange vous informe que cet e-mail a ete controle par l'anti-virus mail.
> > Aucun virus connu a ce jour par nos services n'a ete detecte.
> >
> >
>
> > [ (pas de nom de fichier) (0.2 Ko) ]
> > [ oleg's (28.3 Ko) ]
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: Code formatting and standards
Posted by Tony Poppleton <to...@wanadoo.fr>.
Thanks Oleg.
I would certainly encourage you to try again at enforcing both code formatting and coding standards. The top committers on this project should get together, come up with something they agree on, and then simply enforce it on everyone else. The Eclipse code formatter settings should be made available on the website, as well as the "Clean Up" settings. Eclipse can be used to apply the settings on the whole project, so you can commit one revision where every class will adhere to the new standards.
Thanks,
Tony
> Message du 15/01/10 11:59
> De : "Oleg Kalnichevski"
> A : "Tony Poppleton"
> Copie à : dev@hc.apache.org
> Objet : Re: Code formatting and standards
>
> On Fri, 2010-01-15 at 03:29 +0100, Tony Poppleton wrote:
> > (this was previously posted on the users mailing list by mistake, reposting to the correct channel...)
> >
> > Hi,
> >
> > I use the Eclipse IDE for all my development, and one useful feature is the code formatter to ensure standardization. Does anyone have a premade Eclipse IDE formatter for HttpCore/HttpClient that they could send me please?
> >
>
> Hi Tony
>
> Here is the file containing code formatting settings that I use.
>
>
> > Is code formatting enforced in these projects?
> >
>
> No, not really. The only hard requirement is the use of spaces instead
> of tabs and indentation with 4 spaces.
>
>
> > On a related topic, is there a coding standards document, for example on the usage of the "final" keyword, to ensure coding is consistent between developers?
> >
>
> Historically there used to be too many developers with completely
> different tastes for the code formatting standards, so any attempt at
> coming up with a common policy could easily escalate into a full scale
> 'food fight'. I personally have fairly bizarre preferences for code
> formatting and therefore do not find it possible to impose them onto
> other fellow human beings.
>
> We could try, though, given the fact that the code base is becoming
> stable and major cross cutting changes are unlikely.
>
> Oleg
>
> > Many thanks,
> > Tony
>
>
> ---------------------------------------------------------------------------------------
> Orange vous informe que cet e-mail a ete controle par l'anti-virus mail.
> Aucun virus connu a ce jour par nos services n'a ete detecte.
>
>
> [ (pas de nom de fichier) (0.2 Ko) ]
> [ oleg's (28.3 Ko) ]
Re: Code formatting and standards
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Fri, 2010-01-15 at 03:29 +0100, Tony Poppleton wrote:
> (this was previously posted on the users mailing list by mistake, reposting to the correct channel...)
>
> Hi,
>
> I use the Eclipse IDE for all my development, and one useful feature is the code formatter to ensure standardization. Does anyone have a premade Eclipse IDE formatter for HttpCore/HttpClient that they could send me please?
>
Hi Tony
Here is the file containing code formatting settings that I use.
> Is code formatting enforced in these projects?
>
No, not really. The only hard requirement is the use of spaces instead
of tabs and indentation with 4 spaces.
> On a related topic, is there a coding standards document, for example on the usage of the "final" keyword, to ensure coding is consistent between developers?
>
Historically there used to be too many developers with completely
different tastes for the code formatting standards, so any attempt at
coming up with a common policy could easily escalate into a full scale
'food fight'. I personally have fairly bizarre preferences for code
formatting and therefore do not find it possible to impose them onto
other fellow human beings.
We could try, though, given the fact that the code base is becoming
stable and major cross cutting changes are unlikely.
Oleg
> Many thanks,
> Tony