Proposal: coding standards

[Marcel Offermans <ma...@luminis.nl>]

Since one of the things we should have for Felix is a coding  
standard, I just added a lengthy page on the wiki with a PROPOSAL for  
such a coding standard. In fact, I simply took our company's guide  
(with their permission of course) and made some minor alterations  
(some things were not relevant here). This is meant as a starting  
point, so please read it and give your feedback.

You can read it here on the site (the static copy) and you will  
notice that we need to improve our stylesheet to get better formatting:
http://cwiki.apache.org/FELIX/codingstandards.html

that being said, you can also have a look on the wiki directly (which  
has better built-in styles already):
http://cwiki.apache.org/confluence/display/FELIX/codingstandards

Feel free to comment on anything that's there or missing, voice your  
opinion on what we should and should not try to "standardize". I'm  
particularly interested in your opinions on all the different modules  
(subprojects) and if we should even attempt to enforce any specific  
guide on all of them.

In my experience, agreeing on a coding standard has always been a  
difficult process, because many people have strong personal opinions  
and often, valid points can be made for deciding some things either  
way. The reason to even try to get a standard is easier read- and  
understandability. Oh well, enough talk for one evening!

Greetings, Marcel

Re: Proposal: coding standards

[Karl Pauls <ka...@gmail.com>]

+1 for the code style.

regards,

Karl


On 8/22/06, Ersin Er <er...@gmail.com> wrote:
> Hi all,
>
> On 8/22/06, Marcel Offermans <ma...@luminis.nl> wrote:
>
> > I think the suggestion that Alex put forward to create an Eclipse
> > format for this style would be nice. I also like to integrate a
> > checkstyle like report as Ronald suggested. But both things are steps
> > we should take after agreeing on the standard itself. I will wait for
> > a couple of days and then try to summarize the reactions.
>
> Here is the Eclipse formatting file Alex mentioned:
>
> http://svn.apache.org/viewvc/directory/trunks/resources/formatting.xml?view=markup
>
> > Greetings, Marcel
>
> Cheers,
> --
> Ersin
>


-- 
Karl Pauls
karlpauls@gmail.com

Re: Proposal: coding standards

[Ersin Er <er...@gmail.com>]

Hi all,

On 8/22/06, Marcel Offermans <ma...@luminis.nl> wrote:

> I think the suggestion that Alex put forward to create an Eclipse
> format for this style would be nice. I also like to integrate a
> checkstyle like report as Ronald suggested. But both things are steps
> we should take after agreeing on the standard itself. I will wait for
> a couple of days and then try to summarize the reactions.

Here is the Eclipse formatting file Alex mentioned:

http://svn.apache.org/viewvc/directory/trunks/resources/formatting.xml?view=markup

> Greetings, Marcel

Cheers,
-- 
Ersin

Re: Proposal: coding standards

[Marcel Offermans <ma...@luminis.nl>]

Hello Upayavira,

On Aug 22, 2006, at 0:41 , Upayavira wrote:

> Coding standards in open source projects are an interesting  
> phenomenon,
> in as much as there is really no way to enforce them. Really, all I
> think we could have would be a recommendation. Is that how you were
> offering it?

I put forward this proposal because we should have a coding standard  
on our website according to the guide Ronald mentioned (http:// 
incubator.apache.org/guides/sites.html). Depending on the feedback  
from other committers we will have to figure out how strict we want  
to follow the guide. As I say, it is merely a starting point, but I'm  
happy to see that most things in the guide actually make sense to the  
committers that have reacted so far.

In theory, I think we could even enforce these guidelines if we  
wanted to. Not that I'm proposing we should do that, but if all  
committers would agree that all code should follow the guidelines  
closely then we would not have any problem enforcing that. For the  
code that I maintain, I will make sure it conforms to the standard we  
choose.

I think the suggestion that Alex put forward to create an Eclipse  
format for this style would be nice. I also like to integrate a  
checkstyle like report as Ronald suggested. But both things are steps  
we should take after agreeing on the standard itself. I will wait for  
a couple of days and then try to summarize the reactions.

Greetings, Marcel

RE: Proposal: coding standards

[Ronald Spierenburg <ro...@luminis.nl>]

Upayavira wrote:
> 
> Coding standards in open source projects are an interesting
> phenomenon, in as much as there is really no way to enforce them.
> Really, all I think we could have would be a recommendation.

Perhaps something like CheckStyle could be integrated in the maven build ?

Ronald

Re: Proposal: coding standards

[Upayavira <uv...@odoko.co.uk>]

Marcel Offermans wrote:
> Since one of the things we should have for Felix is a coding standard, I
> just added a lengthy page on the wiki with a PROPOSAL for such a coding
> standard. In fact, I simply took our company's guide (with their
> permission of course) and made some minor alterations (some things were
> not relevant here). This is meant as a starting point, so please read it
> and give your feedback.
> 
> You can read it here on the site (the static copy) and you will notice
> that we need to improve our stylesheet to get better formatting:
> http://cwiki.apache.org/FELIX/codingstandards.html
> 
> that being said, you can also have a look on the wiki directly (which
> has better built-in styles already):
> http://cwiki.apache.org/confluence/display/FELIX/codingstandards
> 
> Feel free to comment on anything that's there or missing, voice your
> opinion on what we should and should not try to "standardize". I'm
> particularly interested in your opinions on all the different modules
> (subprojects) and if we should even attempt to enforce any specific
> guide on all of them.
> 
> In my experience, agreeing on a coding standard has always been a
> difficult process, because many people have strong personal opinions and
> often, valid points can be made for deciding some things either way. The
> reason to even try to get a standard is easier read- and
> understandability. Oh well, enough talk for one evening!

Coding standards in open source projects are an interesting phenomenon,
in as much as there is really no way to enforce them. Really, all I
think we could have would be a recommendation. Is that how you were
offering it?

Upayavira

Re: Proposal: coding standards

[Alex Karasulu <ao...@bellsouth.net>]

Richard S. Hall wrote:
> Overall, the style is fairly close to what I have been using in 
> Oscar/Felix for years now, except for { being on the same line. I am a 
> fan whitespace in code and I find that having the open { on a separate 
> line gives me less dense code that is easier to read. Thus, I could 
> pretty much go with it as is if we could move the { onto a line by itself.

+1

This is exactly the style we use at Directory btw.  I like having things 
clearly spread out. Easier for the eyes to digest.

We have an eclipse format for this style if anybody is interested.

Alex

> -> richard
> 
> Marcel Offermans wrote:
>> Since one of the things we should have for Felix is a coding standard, 
>> I just added a lengthy page on the wiki with a PROPOSAL for such a 
>> coding standard. In fact, I simply took our company's guide (with 
>> their permission of course) and made some minor alterations (some 
>> things were not relevant here). This is meant as a starting point, so 
>> please read it and give your feedback.
>>
>> You can read it here on the site (the static copy) and you will notice 
>> that we need to improve our stylesheet to get better formatting:
>> http://cwiki.apache.org/FELIX/codingstandards.html
>>
>> that being said, you can also have a look on the wiki directly (which 
>> has better built-in styles already):
>> http://cwiki.apache.org/confluence/display/FELIX/codingstandards
>>
>> Feel free to comment on anything that's there or missing, voice your 
>> opinion on what we should and should not try to "standardize". I'm 
>> particularly interested in your opinions on all the different modules 
>> (subprojects) and if we should even attempt to enforce any specific 
>> guide on all of them.
>>
>> In my experience, agreeing on a coding standard has always been a 
>> difficult process, because many people have strong personal opinions 
>> and often, valid points can be made for deciding some things either 
>> way. The reason to even try to get a standard is easier read- and 
>> understandability. Oh well, enough talk for one evening!
>>
>> Greetings, Marcel
>>
> 

Re: Proposal: coding standards

[Benjamin Schmaus <be...@gmail.com>]

> Perhaps it meant "within"...''

Yeah, that seems likely.

On 8/23/06, Richard S. Hall <he...@ungoverned.org> wrote:
> Perhaps it meant "within"...
>
> -> richard
>
> Benjamin Schmaus wrote:
> > Maybe I'm missing something here, but the 2nd sentence under the "File
> > Organization" section reads:
> >
> > "Of course, this excludes inner classes as these must be defined
> > without an (outer) class, and thus in the same file."
> >
> > Shouldn't the "without" be changed to "with"?  By definition, you
> > can't have an inner class without an outer class, right?
> >
> > - Ben
> >
> > PS. I imagine many of you have seen the equinox coding practices doc,
> > but here's the link anyway:
> > http://www.eclipse.org/equinox/documents/coding.php.  It's not as
> > detailed as the Felix doc that's been put together, but it still
> > assists in setting coding expectations.
> >
> > On 8/23/06, Niclas Hedhman <ni...@hedhman.org> wrote:
> >> On Tuesday 22 August 2006 05:11, Richard S. Hall wrote:
> >> > Overall, the style is fairly close to what I have been using in
> >> > Oscar/Felix for years now, except for { being on the same line. I am a
> >> > fan whitespace in code and I find that having the open { on a separate
> >> > line gives me less dense code that is easier to read. Thus, I could
> >> > pretty much go with it as is if we could move the { onto a line by
> >> itself.
> >>
> >> +1 to Marcel's basic and Richard's "opening brace on new line".
> >>
> >> Cheers
> >> Niclas
> >>
>

Re: Proposal: coding standards

["Richard S. Hall" <he...@ungoverned.org>]

Perhaps it meant "within"...

-> richard

Benjamin Schmaus wrote:
> Maybe I'm missing something here, but the 2nd sentence under the "File
> Organization" section reads:
>
> "Of course, this excludes inner classes as these must be defined
> without an (outer) class, and thus in the same file."
>
> Shouldn't the "without" be changed to "with"?  By definition, you
> can't have an inner class without an outer class, right?
>
> - Ben
>
> PS. I imagine many of you have seen the equinox coding practices doc,
> but here's the link anyway:
> http://www.eclipse.org/equinox/documents/coding.php.  It's not as
> detailed as the Felix doc that's been put together, but it still
> assists in setting coding expectations.
>
> On 8/23/06, Niclas Hedhman <ni...@hedhman.org> wrote:
>> On Tuesday 22 August 2006 05:11, Richard S. Hall wrote:
>> > Overall, the style is fairly close to what I have been using in
>> > Oscar/Felix for years now, except for { being on the same line. I am a
>> > fan whitespace in code and I find that having the open { on a separate
>> > line gives me less dense code that is easier to read. Thus, I could
>> > pretty much go with it as is if we could move the { onto a line by 
>> itself.
>>
>> +1 to Marcel's basic and Richard's "opening brace on new line".
>>
>> Cheers
>> Niclas
>>

Re: Proposal: coding standards

[Benjamin Schmaus <be...@gmail.com>]

Maybe I'm missing something here, but the 2nd sentence under the "File
Organization" section reads:

"Of course, this excludes inner classes as these must be defined
without an (outer) class, and thus in the same file."

Shouldn't the "without" be changed to "with"?  By definition, you
can't have an inner class without an outer class, right?

- Ben

PS. I imagine many of you have seen the equinox coding practices doc,
but here's the link anyway:
http://www.eclipse.org/equinox/documents/coding.php.  It's not as
detailed as the Felix doc that's been put together, but it still
assists in setting coding expectations.

On 8/23/06, Niclas Hedhman <ni...@hedhman.org> wrote:
> On Tuesday 22 August 2006 05:11, Richard S. Hall wrote:
> > Overall, the style is fairly close to what I have been using in
> > Oscar/Felix for years now, except for { being on the same line. I am a
> > fan whitespace in code and I find that having the open { on a separate
> > line gives me less dense code that is easier to read. Thus, I could
> > pretty much go with it as is if we could move the { onto a line by itself.
>
> +1 to Marcel's basic and Richard's "opening brace on new line".
>
> Cheers
> Niclas
>

Re: Proposal: coding standards

[Niclas Hedhman <ni...@hedhman.org>]

On Wednesday 23 August 2006 21:35, Richard S. Hall wrote:
> Personally, I am surprised at how little controversy this issue has
> raised. Apparently, the Felix community is not very religious or else we
> all just have the same coding style. :-)

Or the zealots has not woken up yet... ;o) 

Cheers
Niclas

Re: Proposal: coding standards

["Richard S. Hall" <he...@ungoverned.org>]

Personally, I am surprised at how little controversy this issue has 
raised. Apparently, the Felix community is not very religious or else we 
all just have the same coding style. :-)

-> richard

Niclas Hedhman wrote:
> On Tuesday 22 August 2006 05:11, Richard S. Hall wrote:
>   
>> Overall, the style is fairly close to what I have been using in
>> Oscar/Felix for years now, except for { being on the same line. I am a
>> fan whitespace in code and I find that having the open { on a separate
>> line gives me less dense code that is easier to read. Thus, I could
>> pretty much go with it as is if we could move the { onto a line by itself.
>>     
>
> +1 to Marcel's basic and Richard's "opening brace on new line".
>
> Cheers
> Niclas
>   

Re: Proposal: coding standards

[Niclas Hedhman <ni...@hedhman.org>]

On Tuesday 22 August 2006 05:11, Richard S. Hall wrote:
> Overall, the style is fairly close to what I have been using in
> Oscar/Felix for years now, except for { being on the same line. I am a
> fan whitespace in code and I find that having the open { on a separate
> line gives me less dense code that is easier to read. Thus, I could
> pretty much go with it as is if we could move the { onto a line by itself.

+1 to Marcel's basic and Richard's "opening brace on new line".

Cheers
Niclas

Re: Proposal: coding standards

[Rob Walker <ro...@ascert.com>]

I'd also be happy with this, with Richard's modification that the 
opening { is on a line by itself - also a big fan of whitespace in code 
and we've found this a clearer standard here too.

-- Rob

Richard S. Hall wrote:
> Overall, the style is fairly close to what I have been using in 
> Oscar/Felix for years now, except for { being on the same line. I am a 
> fan whitespace in code and I find that having the open { on a separate 
> line gives me less dense code that is easier to read. Thus, I could 
> pretty much go with it as is if we could move the { onto a line by 
> itself.
>
> -> richard
>
> Marcel Offermans wrote:
>> Since one of the things we should have for Felix is a coding 
>> standard, I just added a lengthy page on the wiki with a PROPOSAL for 
>> such a coding standard. In fact, I simply took our company's guide 
>> (with their permission of course) and made some minor alterations 
>> (some things were not relevant here). This is meant as a starting 
>> point, so please read it and give your feedback.
>>
>> You can read it here on the site (the static copy) and you will 
>> notice that we need to improve our stylesheet to get better formatting:
>> http://cwiki.apache.org/FELIX/codingstandards.html
>>
>> that being said, you can also have a look on the wiki directly (which 
>> has better built-in styles already):
>> http://cwiki.apache.org/confluence/display/FELIX/codingstandards
>>
>> Feel free to comment on anything that's there or missing, voice your 
>> opinion on what we should and should not try to "standardize". I'm 
>> particularly interested in your opinions on all the different modules 
>> (subprojects) and if we should even attempt to enforce any specific 
>> guide on all of them.
>>
>> In my experience, agreeing on a coding standard has always been a 
>> difficult process, because many people have strong personal opinions 
>> and often, valid points can be made for deciding some things either 
>> way. The reason to even try to get a standard is easier read- and 
>> understandability. Oh well, enough talk for one evening!
>>
>> Greetings, Marcel
>>

-- 


Ascert - Taking systems to the Edge
robw@ascert.com
+44 (0)20 7488 3470
www.ascert.com

Re: Proposal: coding standards

["Richard S. Hall" <he...@ungoverned.org>]

Overall, the style is fairly close to what I have been using in 
Oscar/Felix for years now, except for { being on the same line. I am a 
fan whitespace in code and I find that having the open { on a separate 
line gives me less dense code that is easier to read. Thus, I could 
pretty much go with it as is if we could move the { onto a line by itself.

-> richard

Marcel Offermans wrote:
> Since one of the things we should have for Felix is a coding standard, 
> I just added a lengthy page on the wiki with a PROPOSAL for such a 
> coding standard. In fact, I simply took our company's guide (with 
> their permission of course) and made some minor alterations (some 
> things were not relevant here). This is meant as a starting point, so 
> please read it and give your feedback.
>
> You can read it here on the site (the static copy) and you will notice 
> that we need to improve our stylesheet to get better formatting:
> http://cwiki.apache.org/FELIX/codingstandards.html
>
> that being said, you can also have a look on the wiki directly (which 
> has better built-in styles already):
> http://cwiki.apache.org/confluence/display/FELIX/codingstandards
>
> Feel free to comment on anything that's there or missing, voice your 
> opinion on what we should and should not try to "standardize". I'm 
> particularly interested in your opinions on all the different modules 
> (subprojects) and if we should even attempt to enforce any specific 
> guide on all of them.
>
> In my experience, agreeing on a coding standard has always been a 
> difficult process, because many people have strong personal opinions 
> and often, valid points can be made for deciding some things either 
> way. The reason to even try to get a standard is easier read- and 
> understandability. Oh well, enough talk for one evening!
>
> Greetings, Marcel
>