You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@geode.apache.org by Kirk Lund <kl...@apache.org> on 2019/06/24 21:15:52 UTC
[DISCUSS] Adoption of a Coding Standard
Apache Geode has a Code Style Guide [1] which is currently defined as
following the Google Java Style Guide [2]. This style guide is a good
starting point, but it deals primarily with formatting of code and is a
fairly dated and static document that doesn't evolve much.
I'd like to propose that the Geode dev community adopt a Coding Standard in
addition to the Style Guide. Specifically, I believe that having our
community follow the SEI CERT Coding Standard [3] for Java [4] would
benefit us greatly. There are also Coding Standards for C and C++ that we
could consider if we decide to use the one for Java.
SEI CERT Coding Standards are completely documented on their wiki which is
open to having anyone join and become involved in their community. They are
also available in book form (including on amazon.com).
From what I've studied, I believe the Coding Standard and Google Java Style
Guide will be compatible, but we could decide that the Coding Standard
supersedes anything in the Google Java Style Guide that is directly in
conflict just in case.
I'm not proposing we rigidly and blindly follow this Coding Standard. We
can extend or even supersede portions of the adopted Coding Standard with
our own Addendum. The Coding Standard Addendum would exist on the Apache
Geode Wiki to define Geode-specific rules or recommendations. What I'd like
to see happen is for us to use the SEI CERT Coding Standard for Java as a
starting point for our own Coding Standard. The resulting Coding Standard
for Geode can be as static or as living and evolving as we wish.
The Coding Standard can then provide helpful guidance in how we reshape
some of the Geode code base that is in greater need of refactoring. It
would also help guide us from following poor examples in the current code
base when introducing new code.
[1] https://cwiki.apache.org/confluence/display/GEODE/Code+Style+Guide
[2] https://google.github.io/styleguide/javaguide.html
[3]
https://wiki.sei.cmu.edu/confluence/display/seccode/SEI+CERT+Coding+Standards
[4]
https://wiki.sei.cmu.edu/confluence/display/java/SEI+CERT+Oracle+Coding+Standard+for+Java
Re: [DISCUSS] Adoption of a Coding Standard
Posted by Kirk Lund <kl...@apache.org>.
>
> What did you like about the SEI rules you suggested? I’m wondering why
> _that_ one versus all the others in the universe?
For me, the book The CERT Oracle Secure Coding Standard for Java is almost
as essential as Effective Java in my library of Java books. As far I know,
there are no other Coding Standards for Java that: a) have a living wiki
and active community, b) a printed version available to purchase if you
prefer a book over a free online wiki, c) contains really great content in
a similar vein with similar quality as Effective Java.
Why, do you know of another that you would recommend over this one?
On Mon, Jun 24, 2019 at 2:45 PM Anthony Baker <ab...@pivotal.io> wrote:
> What did you like about the SEI rules you suggested? I’m wondering why
> _that_ one versus all the others in the universe?
>
> Anthony
>
>
> > On Jun 24, 2019, at 2:15 PM, Kirk Lund <kl...@apache.org> wrote:
> >
> > Apache Geode has a Code Style Guide [1] which is currently defined as
> > following the Google Java Style Guide [2]. This style guide is a good
> > starting point, but it deals primarily with formatting of code and is a
> > fairly dated and static document that doesn't evolve much.
> >
> > I'd like to propose that the Geode dev community adopt a Coding Standard
> in
> > addition to the Style Guide. Specifically, I believe that having our
> > community follow the SEI CERT Coding Standard [3] for Java [4] would
> > benefit us greatly. There are also Coding Standards for C and C++ that we
> > could consider if we decide to use the one for Java.
> >
> > SEI CERT Coding Standards are completely documented on their wiki which
> is
> > open to having anyone join and become involved in their community. They
> are
> > also available in book form (including on amazon.com).
> >
> > From what I've studied, I believe the Coding Standard and Google Java
> Style
> > Guide will be compatible, but we could decide that the Coding Standard
> > supersedes anything in the Google Java Style Guide that is directly in
> > conflict just in case.
> >
> > I'm not proposing we rigidly and blindly follow this Coding Standard. We
> > can extend or even supersede portions of the adopted Coding Standard with
> > our own Addendum. The Coding Standard Addendum would exist on the Apache
> > Geode Wiki to define Geode-specific rules or recommendations. What I'd
> like
> > to see happen is for us to use the SEI CERT Coding Standard for Java as a
> > starting point for our own Coding Standard. The resulting Coding Standard
> > for Geode can be as static or as living and evolving as we wish.
> >
> > The Coding Standard can then provide helpful guidance in how we reshape
> > some of the Geode code base that is in greater need of refactoring. It
> > would also help guide us from following poor examples in the current code
> > base when introducing new code.
> >
> > [1] https://cwiki.apache.org/confluence/display/GEODE/Code+Style+Guide
> > [2] https://google.github.io/styleguide/javaguide.html
> > [3]
> >
> https://wiki.sei.cmu.edu/confluence/display/seccode/SEI+CERT+Coding+Standards
> > [4]
> >
> https://wiki.sei.cmu.edu/confluence/display/java/SEI+CERT+Oracle+Coding+Standard+for+Java
>
>
Re: [DISCUSS] Adoption of a Coding Standard
Posted by Anthony Baker <ab...@pivotal.io>.
What did you like about the SEI rules you suggested? I’m wondering why _that_ one versus all the others in the universe?
Anthony
> On Jun 24, 2019, at 2:15 PM, Kirk Lund <kl...@apache.org> wrote:
>
> Apache Geode has a Code Style Guide [1] which is currently defined as
> following the Google Java Style Guide [2]. This style guide is a good
> starting point, but it deals primarily with formatting of code and is a
> fairly dated and static document that doesn't evolve much.
>
> I'd like to propose that the Geode dev community adopt a Coding Standard in
> addition to the Style Guide. Specifically, I believe that having our
> community follow the SEI CERT Coding Standard [3] for Java [4] would
> benefit us greatly. There are also Coding Standards for C and C++ that we
> could consider if we decide to use the one for Java.
>
> SEI CERT Coding Standards are completely documented on their wiki which is
> open to having anyone join and become involved in their community. They are
> also available in book form (including on amazon.com).
>
> From what I've studied, I believe the Coding Standard and Google Java Style
> Guide will be compatible, but we could decide that the Coding Standard
> supersedes anything in the Google Java Style Guide that is directly in
> conflict just in case.
>
> I'm not proposing we rigidly and blindly follow this Coding Standard. We
> can extend or even supersede portions of the adopted Coding Standard with
> our own Addendum. The Coding Standard Addendum would exist on the Apache
> Geode Wiki to define Geode-specific rules or recommendations. What I'd like
> to see happen is for us to use the SEI CERT Coding Standard for Java as a
> starting point for our own Coding Standard. The resulting Coding Standard
> for Geode can be as static or as living and evolving as we wish.
>
> The Coding Standard can then provide helpful guidance in how we reshape
> some of the Geode code base that is in greater need of refactoring. It
> would also help guide us from following poor examples in the current code
> base when introducing new code.
>
> [1] https://cwiki.apache.org/confluence/display/GEODE/Code+Style+Guide
> [2] https://google.github.io/styleguide/javaguide.html
> [3]
> https://wiki.sei.cmu.edu/confluence/display/seccode/SEI+CERT+Coding+Standards
> [4]
> https://wiki.sei.cmu.edu/confluence/display/java/SEI+CERT+Oracle+Coding+Standard+for+Java
Re: [DISCUSS] Adoption of a Coding Standard
Posted by Bruce Schuchardt <bs...@pivotal.io>.
Maybe we need a "recommended reading" list more than we need a
non-enforceable standard. The Oracle wiki has a lot of good
correct/incorrect examples that people could learn from if they take the
time to read through it all.
On 6/24/19 3:15 PM, Kirk Lund wrote:
> Java is complicated and Apache Geode is complicated, hence it's a large
> Coding Standard. *Effective Java* is similarly *large* if you compare it to
> the *Google Java Style Guide*.
>
> The "*rules*" are "*guidelines*" -- I think you're being too literal. Also,
> please remember what I said:
>
> I'm not proposing we rigidly and blindly follow this Coding Standard. We
>> can extend or even supersede portions of the adopted Coding Standard with
>> our own Addendum. The Coding Standard Addendum would exist on the Apache
>> Geode Wiki to define Geode-specific rules or recommendations. What I'd like
>> to see happen is for us to use the SEI CERT Coding Standard for Java as a
>> starting point for our own Coding Standard. The resulting Coding Standard
>> for Geode can be as static or as living and evolving as we wish.
>>
> Is there an entry in the Coding Standard's Rules section that you feel is
> irrelevant or incorrect? Please pick an example with a link to it so we can
> discuss it.
>
> PS: There aren't any other Coding Standards that I would personally write
> or recommend.
>
> On Mon, Jun 24, 2019 at 2:50 PM Alexander Murmann <am...@apache.org>
> wrote:
>
>> Hi Kirk,
>>
>> I think having a coding standard that goes beyond a formatting style guide
>> is a great idea. There are many interesting things in the SEI CERT
>> standard. However, it's also massive. I see 13 rules just about methods.
>> Yet some guidelines that would be most important to me like limiting method
>> length and number of parameters are missing.
>>
>> I wonder if we might be better off taking the rules we like from SEI CERT,
>> adding our own and aiming for a much smaller set of guidelines. I'd hope
>> for something like a one-pager. If it gets much longer than that, it
>> becomes burdensome to read for newcomers and we want to make sure they can
>> quickly take in what's most important.
>>
>> I also prefer "guidelines" over "rules". I'd like to have a discussion if
>> someone is not following a guideline, rather than creating the impression
>> that all rules must be followed, no matter what the circumstances are.
>>
>>
>> On Mon, Jun 24, 2019 at 2:16 PM Kirk Lund <kl...@apache.org> wrote:
>>
>>> Apache Geode has a Code Style Guide [1] which is currently defined as
>>> following the Google Java Style Guide [2]. This style guide is a good
>>> starting point, but it deals primarily with formatting of code and is a
>>> fairly dated and static document that doesn't evolve much.
>>>
>>> I'd like to propose that the Geode dev community adopt a Coding Standard
>> in
>>> addition to the Style Guide. Specifically, I believe that having our
>>> community follow the SEI CERT Coding Standard [3] for Java [4] would
>>> benefit us greatly. There are also Coding Standards for C and C++ that we
>>> could consider if we decide to use the one for Java.
>>>
>>> SEI CERT Coding Standards are completely documented on their wiki which
>> is
>>> open to having anyone join and become involved in their community. They
>> are
>>> also available in book form (including on amazon.com).
>>>
>>> From what I've studied, I believe the Coding Standard and Google Java
>> Style
>>> Guide will be compatible, but we could decide that the Coding Standard
>>> supersedes anything in the Google Java Style Guide that is directly in
>>> conflict just in case.
>>>
>>> I'm not proposing we rigidly and blindly follow this Coding Standard. We
>>> can extend or even supersede portions of the adopted Coding Standard with
>>> our own Addendum. The Coding Standard Addendum would exist on the Apache
>>> Geode Wiki to define Geode-specific rules or recommendations. What I'd
>> like
>>> to see happen is for us to use the SEI CERT Coding Standard for Java as a
>>> starting point for our own Coding Standard. The resulting Coding Standard
>>> for Geode can be as static or as living and evolving as we wish.
>>>
>>> The Coding Standard can then provide helpful guidance in how we reshape
>>> some of the Geode code base that is in greater need of refactoring. It
>>> would also help guide us from following poor examples in the current code
>>> base when introducing new code.
>>>
>>> [1] https://cwiki.apache.org/confluence/display/GEODE/Code+Style+Guide
>>> [2] https://google.github.io/styleguide/javaguide.html
>>> [3]
>>>
>>>
>> https://wiki.sei.cmu.edu/confluence/display/seccode/SEI+CERT+Coding+Standards
>>> [4]
>>>
>>>
>> https://wiki.sei.cmu.edu/confluence/display/java/SEI+CERT+Oracle+Coding+Standard+for+Java
Re: [DISCUSS] Adoption of a Coding Standard
Posted by Ernest Burghardt <eb...@pivotal.io>.
Here's some food for thought on creating coding standards...
1. You can't please everyone all of the time or in all aspects and this
becomes "Hero" driven or a "holy war"
2. Creating a custom standard is very time/resource consuming and (see #1)
3. Adopting an objectively maintained industry coding standard will suffice
in most cases (maybe the Geode standard only addresses edge cases where
Geode deviates from the Google or SEI...)
+1 to Bruce's idea to make the books recommended reading
On Thu, Jun 27, 2019 at 9:59 AM Aaron Lindsey <al...@pivotal.io> wrote:
> +1 to having a recommended reading list. At first glance, the SEI standard
> seems like an extremely useful resource, but I am hesitant to adopt it as
> our "coding standard" without carefully reading all the way through it. I
> would, however, be comfortable adding it to a recommended reading list.
>
> - Aaron
>
>
> On Mon, Jun 24, 2019 at 4:28 PM Owen Nichols <on...@pivotal.io> wrote:
>
> > I like the idea of a recommended reading list for Geode contributors.
> >
> > My concerns around adopting broad standards and guidelines that can’t be
> > automatically checked & applied are twofold:
> >
> > a) what is the policy regarding existing code? Is every PR going
> forward
> > expected to bring every file it touches into conformance?
> >
> > b) how do we avoid PR reviews devolving into style-nitpicking? If a PR
> > clearly fixes a bug, but someone doesn’t like a variable name, would that
> > be reason to give it a -1?
> >
> > Even better would be leading by example [if we can’t overhaul the entire
> > codebase, maybe at least be able to point to one file that really
> embodies
> > our desired coding standards].
> >
> > People over process. Code is either readable or it isn’t. If you are
> > reviewing a PR and the proposed changes are difficult to follow, a simple
> > and kind explanation is probably more constructive than citing the
> offender
> > with the chapter and section of their violation.
> >
> >
> >
> > > On Jun 24, 2019, at 3:31 PM, Alexander Murmann <am...@apache.org>
> > wrote:
> > >
> > >> Is there an entry in the Coding Standard's Rules section that you feel
> > is
> > > irrelevant or incorrect? Please pick an example with a link to it so we
> > can
> > > discuss it.
> > >
> > > I haven't seen any rules in there that I think are irrelevant or
> > incorrect.
> > > My reasoning is a little different from that:
> > > I think there are two different, competing goals we can optimize for:
> > > a) The rules should be as complete as possible.
> > > b) New contributors should be able to quickly catch up to what the
> coding
> > > standard is for this project.
> > >
> > > I'd rather optimize for a) over b). To that end I'd prefer to leave
> > > absolutely valid, but arguably obvious rules like MET02-J. Do not use
> > > deprecated or obsolete classes or methods
> > > <
> >
> https://wiki.sei.cmu.edu/confluence/display/java/MET02-J.+Do+not+use+deprecated+or+obsolete+classes+or+methods
> > >
> > > or IDS00-J. Prevent SQL injection
> > > <
> >
> https://wiki.sei.cmu.edu/confluence/display/java/IDS00-J.+Prevent+SQL+injection
> > >
> > > off
> > > and instead highlight the ways we are more opinionated then some other
> > Java
> > > projects (e.g. "Avoid introducing new statics", "limit method length",
> > > "don't use abbreviated names")
> > >
> > > We could also go down the path of a compromise and highlight the rules
> we
> > > care most about that will allow someone who is already a competent
> > > developer to get up to speed quickly on our project and refer to the
> SEI
> > > CERT rules as a recommended read for developers who are newer to Java.
> > The
> > > difference to your proposal would be that the Geode wiki page would
> > > highlight what's most important and potentially surprising rather than
> be
> > > an addendum to the already very large corpus of SEI CERT rules.
> > >
> > >
> > > On Mon, Jun 24, 2019 at 3:15 PM Kirk Lund <kl...@apache.org> wrote:
> > >
> > >> Java is complicated and Apache Geode is complicated, hence it's a
> large
> > >> Coding Standard. *Effective Java* is similarly *large* if you compare
> > it to
> > >> the *Google Java Style Guide*.
> > >>
> > >> The "*rules*" are "*guidelines*" -- I think you're being too literal.
> > Also,
> > >> please remember what I said:
> > >>
> > >> I'm not proposing we rigidly and blindly follow this Coding Standard.
> We
> > >>> can extend or even supersede portions of the adopted Coding Standard
> > with
> > >>> our own Addendum. The Coding Standard Addendum would exist on the
> > Apache
> > >>> Geode Wiki to define Geode-specific rules or recommendations. What
> I'd
> > >> like
> > >>> to see happen is for us to use the SEI CERT Coding Standard for Java
> > as a
> > >>> starting point for our own Coding Standard. The resulting Coding
> > Standard
> > >>> for Geode can be as static or as living and evolving as we wish.
> > >>>
> > >>
> > >> Is there an entry in the Coding Standard's Rules section that you feel
> > is
> > >> irrelevant or incorrect? Please pick an example with a link to it so
> we
> > can
> > >> discuss it.
> > >>
> > >> PS: There aren't any other Coding Standards that I would personally
> > write
> > >> or recommend.
> > >>
> > >> On Mon, Jun 24, 2019 at 2:50 PM Alexander Murmann <
> amurmann@apache.org>
> > >> wrote:
> > >>
> > >>> Hi Kirk,
> > >>>
> > >>> I think having a coding standard that goes beyond a formatting style
> > >> guide
> > >>> is a great idea. There are many interesting things in the SEI CERT
> > >>> standard. However, it's also massive. I see 13 rules just about
> > methods.
> > >>> Yet some guidelines that would be most important to me like limiting
> > >> method
> > >>> length and number of parameters are missing.
> > >>>
> > >>> I wonder if we might be better off taking the rules we like from SEI
> > >> CERT,
> > >>> adding our own and aiming for a much smaller set of guidelines. I'd
> > hope
> > >>> for something like a one-pager. If it gets much longer than that, it
> > >>> becomes burdensome to read for newcomers and we want to make sure
> they
> > >> can
> > >>> quickly take in what's most important.
> > >>>
> > >>> I also prefer "guidelines" over "rules". I'd like to have a
> discussion
> > if
> > >>> someone is not following a guideline, rather than creating the
> > impression
> > >>> that all rules must be followed, no matter what the circumstances
> are.
> > >>>
> > >>>
> > >>> On Mon, Jun 24, 2019 at 2:16 PM Kirk Lund <kl...@apache.org> wrote:
> > >>>
> > >>>> Apache Geode has a Code Style Guide [1] which is currently defined
> as
> > >>>> following the Google Java Style Guide [2]. This style guide is a
> good
> > >>>> starting point, but it deals primarily with formatting of code and
> is
> > a
> > >>>> fairly dated and static document that doesn't evolve much.
> > >>>>
> > >>>> I'd like to propose that the Geode dev community adopt a Coding
> > >> Standard
> > >>> in
> > >>>> addition to the Style Guide. Specifically, I believe that having our
> > >>>> community follow the SEI CERT Coding Standard [3] for Java [4] would
> > >>>> benefit us greatly. There are also Coding Standards for C and C++
> that
> > >> we
> > >>>> could consider if we decide to use the one for Java.
> > >>>>
> > >>>> SEI CERT Coding Standards are completely documented on their wiki
> > which
> > >>> is
> > >>>> open to having anyone join and become involved in their community.
> > They
> > >>> are
> > >>>> also available in book form (including on amazon.com).
> > >>>>
> > >>>> From what I've studied, I believe the Coding Standard and Google
> Java
> > >>> Style
> > >>>> Guide will be compatible, but we could decide that the Coding
> Standard
> > >>>> supersedes anything in the Google Java Style Guide that is directly
> in
> > >>>> conflict just in case.
> > >>>>
> > >>>> I'm not proposing we rigidly and blindly follow this Coding
> Standard.
> > >> We
> > >>>> can extend or even supersede portions of the adopted Coding Standard
> > >> with
> > >>>> our own Addendum. The Coding Standard Addendum would exist on the
> > >> Apache
> > >>>> Geode Wiki to define Geode-specific rules or recommendations. What
> I'd
> > >>> like
> > >>>> to see happen is for us to use the SEI CERT Coding Standard for Java
> > >> as a
> > >>>> starting point for our own Coding Standard. The resulting Coding
> > >> Standard
> > >>>> for Geode can be as static or as living and evolving as we wish.
> > >>>>
> > >>>> The Coding Standard can then provide helpful guidance in how we
> > reshape
> > >>>> some of the Geode code base that is in greater need of refactoring.
> It
> > >>>> would also help guide us from following poor examples in the current
> > >> code
> > >>>> base when introducing new code.
> > >>>>
> > >>>> [1]
> > https://cwiki.apache.org/confluence/display/GEODE/Code+Style+Guide
> > >>>> [2] https://google.github.io/styleguide/javaguide.html
> > >>>> [3]
> > >>>>
> > >>>>
> > >>>
> > >>
> >
> https://wiki.sei.cmu.edu/confluence/display/seccode/SEI+CERT+Coding+Standards
> > >>>> [4]
> > >>>>
> > >>>>
> > >>>
> > >>
> >
> https://wiki.sei.cmu.edu/confluence/display/java/SEI+CERT+Oracle+Coding+Standard+for+Java
> > >>>>
> > >>>
> > >>
> >
> >
>
Re: [DISCUSS] Adoption of a Coding Standard
Posted by Aaron Lindsey <al...@pivotal.io>.
+1 to having a recommended reading list. At first glance, the SEI standard
seems like an extremely useful resource, but I am hesitant to adopt it as
our "coding standard" without carefully reading all the way through it. I
would, however, be comfortable adding it to a recommended reading list.
- Aaron
On Mon, Jun 24, 2019 at 4:28 PM Owen Nichols <on...@pivotal.io> wrote:
> I like the idea of a recommended reading list for Geode contributors.
>
> My concerns around adopting broad standards and guidelines that can’t be
> automatically checked & applied are twofold:
>
> a) what is the policy regarding existing code? Is every PR going forward
> expected to bring every file it touches into conformance?
>
> b) how do we avoid PR reviews devolving into style-nitpicking? If a PR
> clearly fixes a bug, but someone doesn’t like a variable name, would that
> be reason to give it a -1?
>
> Even better would be leading by example [if we can’t overhaul the entire
> codebase, maybe at least be able to point to one file that really embodies
> our desired coding standards].
>
> People over process. Code is either readable or it isn’t. If you are
> reviewing a PR and the proposed changes are difficult to follow, a simple
> and kind explanation is probably more constructive than citing the offender
> with the chapter and section of their violation.
>
>
>
> > On Jun 24, 2019, at 3:31 PM, Alexander Murmann <am...@apache.org>
> wrote:
> >
> >> Is there an entry in the Coding Standard's Rules section that you feel
> is
> > irrelevant or incorrect? Please pick an example with a link to it so we
> can
> > discuss it.
> >
> > I haven't seen any rules in there that I think are irrelevant or
> incorrect.
> > My reasoning is a little different from that:
> > I think there are two different, competing goals we can optimize for:
> > a) The rules should be as complete as possible.
> > b) New contributors should be able to quickly catch up to what the coding
> > standard is for this project.
> >
> > I'd rather optimize for a) over b). To that end I'd prefer to leave
> > absolutely valid, but arguably obvious rules like MET02-J. Do not use
> > deprecated or obsolete classes or methods
> > <
> https://wiki.sei.cmu.edu/confluence/display/java/MET02-J.+Do+not+use+deprecated+or+obsolete+classes+or+methods
> >
> > or IDS00-J. Prevent SQL injection
> > <
> https://wiki.sei.cmu.edu/confluence/display/java/IDS00-J.+Prevent+SQL+injection
> >
> > off
> > and instead highlight the ways we are more opinionated then some other
> Java
> > projects (e.g. "Avoid introducing new statics", "limit method length",
> > "don't use abbreviated names")
> >
> > We could also go down the path of a compromise and highlight the rules we
> > care most about that will allow someone who is already a competent
> > developer to get up to speed quickly on our project and refer to the SEI
> > CERT rules as a recommended read for developers who are newer to Java.
> The
> > difference to your proposal would be that the Geode wiki page would
> > highlight what's most important and potentially surprising rather than be
> > an addendum to the already very large corpus of SEI CERT rules.
> >
> >
> > On Mon, Jun 24, 2019 at 3:15 PM Kirk Lund <kl...@apache.org> wrote:
> >
> >> Java is complicated and Apache Geode is complicated, hence it's a large
> >> Coding Standard. *Effective Java* is similarly *large* if you compare
> it to
> >> the *Google Java Style Guide*.
> >>
> >> The "*rules*" are "*guidelines*" -- I think you're being too literal.
> Also,
> >> please remember what I said:
> >>
> >> I'm not proposing we rigidly and blindly follow this Coding Standard. We
> >>> can extend or even supersede portions of the adopted Coding Standard
> with
> >>> our own Addendum. The Coding Standard Addendum would exist on the
> Apache
> >>> Geode Wiki to define Geode-specific rules or recommendations. What I'd
> >> like
> >>> to see happen is for us to use the SEI CERT Coding Standard for Java
> as a
> >>> starting point for our own Coding Standard. The resulting Coding
> Standard
> >>> for Geode can be as static or as living and evolving as we wish.
> >>>
> >>
> >> Is there an entry in the Coding Standard's Rules section that you feel
> is
> >> irrelevant or incorrect? Please pick an example with a link to it so we
> can
> >> discuss it.
> >>
> >> PS: There aren't any other Coding Standards that I would personally
> write
> >> or recommend.
> >>
> >> On Mon, Jun 24, 2019 at 2:50 PM Alexander Murmann <am...@apache.org>
> >> wrote:
> >>
> >>> Hi Kirk,
> >>>
> >>> I think having a coding standard that goes beyond a formatting style
> >> guide
> >>> is a great idea. There are many interesting things in the SEI CERT
> >>> standard. However, it's also massive. I see 13 rules just about
> methods.
> >>> Yet some guidelines that would be most important to me like limiting
> >> method
> >>> length and number of parameters are missing.
> >>>
> >>> I wonder if we might be better off taking the rules we like from SEI
> >> CERT,
> >>> adding our own and aiming for a much smaller set of guidelines. I'd
> hope
> >>> for something like a one-pager. If it gets much longer than that, it
> >>> becomes burdensome to read for newcomers and we want to make sure they
> >> can
> >>> quickly take in what's most important.
> >>>
> >>> I also prefer "guidelines" over "rules". I'd like to have a discussion
> if
> >>> someone is not following a guideline, rather than creating the
> impression
> >>> that all rules must be followed, no matter what the circumstances are.
> >>>
> >>>
> >>> On Mon, Jun 24, 2019 at 2:16 PM Kirk Lund <kl...@apache.org> wrote:
> >>>
> >>>> Apache Geode has a Code Style Guide [1] which is currently defined as
> >>>> following the Google Java Style Guide [2]. This style guide is a good
> >>>> starting point, but it deals primarily with formatting of code and is
> a
> >>>> fairly dated and static document that doesn't evolve much.
> >>>>
> >>>> I'd like to propose that the Geode dev community adopt a Coding
> >> Standard
> >>> in
> >>>> addition to the Style Guide. Specifically, I believe that having our
> >>>> community follow the SEI CERT Coding Standard [3] for Java [4] would
> >>>> benefit us greatly. There are also Coding Standards for C and C++ that
> >> we
> >>>> could consider if we decide to use the one for Java.
> >>>>
> >>>> SEI CERT Coding Standards are completely documented on their wiki
> which
> >>> is
> >>>> open to having anyone join and become involved in their community.
> They
> >>> are
> >>>> also available in book form (including on amazon.com).
> >>>>
> >>>> From what I've studied, I believe the Coding Standard and Google Java
> >>> Style
> >>>> Guide will be compatible, but we could decide that the Coding Standard
> >>>> supersedes anything in the Google Java Style Guide that is directly in
> >>>> conflict just in case.
> >>>>
> >>>> I'm not proposing we rigidly and blindly follow this Coding Standard.
> >> We
> >>>> can extend or even supersede portions of the adopted Coding Standard
> >> with
> >>>> our own Addendum. The Coding Standard Addendum would exist on the
> >> Apache
> >>>> Geode Wiki to define Geode-specific rules or recommendations. What I'd
> >>> like
> >>>> to see happen is for us to use the SEI CERT Coding Standard for Java
> >> as a
> >>>> starting point for our own Coding Standard. The resulting Coding
> >> Standard
> >>>> for Geode can be as static or as living and evolving as we wish.
> >>>>
> >>>> The Coding Standard can then provide helpful guidance in how we
> reshape
> >>>> some of the Geode code base that is in greater need of refactoring. It
> >>>> would also help guide us from following poor examples in the current
> >> code
> >>>> base when introducing new code.
> >>>>
> >>>> [1]
> https://cwiki.apache.org/confluence/display/GEODE/Code+Style+Guide
> >>>> [2] https://google.github.io/styleguide/javaguide.html
> >>>> [3]
> >>>>
> >>>>
> >>>
> >>
> https://wiki.sei.cmu.edu/confluence/display/seccode/SEI+CERT+Coding+Standards
> >>>> [4]
> >>>>
> >>>>
> >>>
> >>
> https://wiki.sei.cmu.edu/confluence/display/java/SEI+CERT+Oracle+Coding+Standard+for+Java
> >>>>
> >>>
> >>
>
>
Re: [DISCUSS] Adoption of a Coding Standard
Posted by Owen Nichols <on...@pivotal.io>.
I like the idea of a recommended reading list for Geode contributors.
My concerns around adopting broad standards and guidelines that can’t be automatically checked & applied are twofold:
a) what is the policy regarding existing code? Is every PR going forward expected to bring every file it touches into conformance?
b) how do we avoid PR reviews devolving into style-nitpicking? If a PR clearly fixes a bug, but someone doesn’t like a variable name, would that be reason to give it a -1?
Even better would be leading by example [if we can’t overhaul the entire codebase, maybe at least be able to point to one file that really embodies our desired coding standards].
People over process. Code is either readable or it isn’t. If you are reviewing a PR and the proposed changes are difficult to follow, a simple and kind explanation is probably more constructive than citing the offender with the chapter and section of their violation.
> On Jun 24, 2019, at 3:31 PM, Alexander Murmann <am...@apache.org> wrote:
>
>> Is there an entry in the Coding Standard's Rules section that you feel is
> irrelevant or incorrect? Please pick an example with a link to it so we can
> discuss it.
>
> I haven't seen any rules in there that I think are irrelevant or incorrect.
> My reasoning is a little different from that:
> I think there are two different, competing goals we can optimize for:
> a) The rules should be as complete as possible.
> b) New contributors should be able to quickly catch up to what the coding
> standard is for this project.
>
> I'd rather optimize for a) over b). To that end I'd prefer to leave
> absolutely valid, but arguably obvious rules like MET02-J. Do not use
> deprecated or obsolete classes or methods
> <https://wiki.sei.cmu.edu/confluence/display/java/MET02-J.+Do+not+use+deprecated+or+obsolete+classes+or+methods>
> or IDS00-J. Prevent SQL injection
> <https://wiki.sei.cmu.edu/confluence/display/java/IDS00-J.+Prevent+SQL+injection>
> off
> and instead highlight the ways we are more opinionated then some other Java
> projects (e.g. "Avoid introducing new statics", "limit method length",
> "don't use abbreviated names")
>
> We could also go down the path of a compromise and highlight the rules we
> care most about that will allow someone who is already a competent
> developer to get up to speed quickly on our project and refer to the SEI
> CERT rules as a recommended read for developers who are newer to Java. The
> difference to your proposal would be that the Geode wiki page would
> highlight what's most important and potentially surprising rather than be
> an addendum to the already very large corpus of SEI CERT rules.
>
>
> On Mon, Jun 24, 2019 at 3:15 PM Kirk Lund <kl...@apache.org> wrote:
>
>> Java is complicated and Apache Geode is complicated, hence it's a large
>> Coding Standard. *Effective Java* is similarly *large* if you compare it to
>> the *Google Java Style Guide*.
>>
>> The "*rules*" are "*guidelines*" -- I think you're being too literal. Also,
>> please remember what I said:
>>
>> I'm not proposing we rigidly and blindly follow this Coding Standard. We
>>> can extend or even supersede portions of the adopted Coding Standard with
>>> our own Addendum. The Coding Standard Addendum would exist on the Apache
>>> Geode Wiki to define Geode-specific rules or recommendations. What I'd
>> like
>>> to see happen is for us to use the SEI CERT Coding Standard for Java as a
>>> starting point for our own Coding Standard. The resulting Coding Standard
>>> for Geode can be as static or as living and evolving as we wish.
>>>
>>
>> Is there an entry in the Coding Standard's Rules section that you feel is
>> irrelevant or incorrect? Please pick an example with a link to it so we can
>> discuss it.
>>
>> PS: There aren't any other Coding Standards that I would personally write
>> or recommend.
>>
>> On Mon, Jun 24, 2019 at 2:50 PM Alexander Murmann <am...@apache.org>
>> wrote:
>>
>>> Hi Kirk,
>>>
>>> I think having a coding standard that goes beyond a formatting style
>> guide
>>> is a great idea. There are many interesting things in the SEI CERT
>>> standard. However, it's also massive. I see 13 rules just about methods.
>>> Yet some guidelines that would be most important to me like limiting
>> method
>>> length and number of parameters are missing.
>>>
>>> I wonder if we might be better off taking the rules we like from SEI
>> CERT,
>>> adding our own and aiming for a much smaller set of guidelines. I'd hope
>>> for something like a one-pager. If it gets much longer than that, it
>>> becomes burdensome to read for newcomers and we want to make sure they
>> can
>>> quickly take in what's most important.
>>>
>>> I also prefer "guidelines" over "rules". I'd like to have a discussion if
>>> someone is not following a guideline, rather than creating the impression
>>> that all rules must be followed, no matter what the circumstances are.
>>>
>>>
>>> On Mon, Jun 24, 2019 at 2:16 PM Kirk Lund <kl...@apache.org> wrote:
>>>
>>>> Apache Geode has a Code Style Guide [1] which is currently defined as
>>>> following the Google Java Style Guide [2]. This style guide is a good
>>>> starting point, but it deals primarily with formatting of code and is a
>>>> fairly dated and static document that doesn't evolve much.
>>>>
>>>> I'd like to propose that the Geode dev community adopt a Coding
>> Standard
>>> in
>>>> addition to the Style Guide. Specifically, I believe that having our
>>>> community follow the SEI CERT Coding Standard [3] for Java [4] would
>>>> benefit us greatly. There are also Coding Standards for C and C++ that
>> we
>>>> could consider if we decide to use the one for Java.
>>>>
>>>> SEI CERT Coding Standards are completely documented on their wiki which
>>> is
>>>> open to having anyone join and become involved in their community. They
>>> are
>>>> also available in book form (including on amazon.com).
>>>>
>>>> From what I've studied, I believe the Coding Standard and Google Java
>>> Style
>>>> Guide will be compatible, but we could decide that the Coding Standard
>>>> supersedes anything in the Google Java Style Guide that is directly in
>>>> conflict just in case.
>>>>
>>>> I'm not proposing we rigidly and blindly follow this Coding Standard.
>> We
>>>> can extend or even supersede portions of the adopted Coding Standard
>> with
>>>> our own Addendum. The Coding Standard Addendum would exist on the
>> Apache
>>>> Geode Wiki to define Geode-specific rules or recommendations. What I'd
>>> like
>>>> to see happen is for us to use the SEI CERT Coding Standard for Java
>> as a
>>>> starting point for our own Coding Standard. The resulting Coding
>> Standard
>>>> for Geode can be as static or as living and evolving as we wish.
>>>>
>>>> The Coding Standard can then provide helpful guidance in how we reshape
>>>> some of the Geode code base that is in greater need of refactoring. It
>>>> would also help guide us from following poor examples in the current
>> code
>>>> base when introducing new code.
>>>>
>>>> [1] https://cwiki.apache.org/confluence/display/GEODE/Code+Style+Guide
>>>> [2] https://google.github.io/styleguide/javaguide.html
>>>> [3]
>>>>
>>>>
>>>
>> https://wiki.sei.cmu.edu/confluence/display/seccode/SEI+CERT+Coding+Standards
>>>> [4]
>>>>
>>>>
>>>
>> https://wiki.sei.cmu.edu/confluence/display/java/SEI+CERT+Oracle+Coding+Standard+for+Java
>>>>
>>>
>>
Re: [DISCUSS] Adoption of a Coding Standard
Posted by Alexander Murmann <am...@apache.org>.
> Is there an entry in the Coding Standard's Rules section that you feel is
irrelevant or incorrect? Please pick an example with a link to it so we can
discuss it.
I haven't seen any rules in there that I think are irrelevant or incorrect.
My reasoning is a little different from that:
I think there are two different, competing goals we can optimize for:
a) The rules should be as complete as possible.
b) New contributors should be able to quickly catch up to what the coding
standard is for this project.
I'd rather optimize for a) over b). To that end I'd prefer to leave
absolutely valid, but arguably obvious rules like MET02-J. Do not use
deprecated or obsolete classes or methods
<https://wiki.sei.cmu.edu/confluence/display/java/MET02-J.+Do+not+use+deprecated+or+obsolete+classes+or+methods>
or IDS00-J. Prevent SQL injection
<https://wiki.sei.cmu.edu/confluence/display/java/IDS00-J.+Prevent+SQL+injection>
off
and instead highlight the ways we are more opinionated then some other Java
projects (e.g. "Avoid introducing new statics", "limit method length",
"don't use abbreviated names")
We could also go down the path of a compromise and highlight the rules we
care most about that will allow someone who is already a competent
developer to get up to speed quickly on our project and refer to the SEI
CERT rules as a recommended read for developers who are newer to Java. The
difference to your proposal would be that the Geode wiki page would
highlight what's most important and potentially surprising rather than be
an addendum to the already very large corpus of SEI CERT rules.
On Mon, Jun 24, 2019 at 3:15 PM Kirk Lund <kl...@apache.org> wrote:
> Java is complicated and Apache Geode is complicated, hence it's a large
> Coding Standard. *Effective Java* is similarly *large* if you compare it to
> the *Google Java Style Guide*.
>
> The "*rules*" are "*guidelines*" -- I think you're being too literal. Also,
> please remember what I said:
>
> I'm not proposing we rigidly and blindly follow this Coding Standard. We
> > can extend or even supersede portions of the adopted Coding Standard with
> > our own Addendum. The Coding Standard Addendum would exist on the Apache
> > Geode Wiki to define Geode-specific rules or recommendations. What I'd
> like
> > to see happen is for us to use the SEI CERT Coding Standard for Java as a
> > starting point for our own Coding Standard. The resulting Coding Standard
> > for Geode can be as static or as living and evolving as we wish.
> >
>
> Is there an entry in the Coding Standard's Rules section that you feel is
> irrelevant or incorrect? Please pick an example with a link to it so we can
> discuss it.
>
> PS: There aren't any other Coding Standards that I would personally write
> or recommend.
>
> On Mon, Jun 24, 2019 at 2:50 PM Alexander Murmann <am...@apache.org>
> wrote:
>
> > Hi Kirk,
> >
> > I think having a coding standard that goes beyond a formatting style
> guide
> > is a great idea. There are many interesting things in the SEI CERT
> > standard. However, it's also massive. I see 13 rules just about methods.
> > Yet some guidelines that would be most important to me like limiting
> method
> > length and number of parameters are missing.
> >
> > I wonder if we might be better off taking the rules we like from SEI
> CERT,
> > adding our own and aiming for a much smaller set of guidelines. I'd hope
> > for something like a one-pager. If it gets much longer than that, it
> > becomes burdensome to read for newcomers and we want to make sure they
> can
> > quickly take in what's most important.
> >
> > I also prefer "guidelines" over "rules". I'd like to have a discussion if
> > someone is not following a guideline, rather than creating the impression
> > that all rules must be followed, no matter what the circumstances are.
> >
> >
> > On Mon, Jun 24, 2019 at 2:16 PM Kirk Lund <kl...@apache.org> wrote:
> >
> > > Apache Geode has a Code Style Guide [1] which is currently defined as
> > > following the Google Java Style Guide [2]. This style guide is a good
> > > starting point, but it deals primarily with formatting of code and is a
> > > fairly dated and static document that doesn't evolve much.
> > >
> > > I'd like to propose that the Geode dev community adopt a Coding
> Standard
> > in
> > > addition to the Style Guide. Specifically, I believe that having our
> > > community follow the SEI CERT Coding Standard [3] for Java [4] would
> > > benefit us greatly. There are also Coding Standards for C and C++ that
> we
> > > could consider if we decide to use the one for Java.
> > >
> > > SEI CERT Coding Standards are completely documented on their wiki which
> > is
> > > open to having anyone join and become involved in their community. They
> > are
> > > also available in book form (including on amazon.com).
> > >
> > > From what I've studied, I believe the Coding Standard and Google Java
> > Style
> > > Guide will be compatible, but we could decide that the Coding Standard
> > > supersedes anything in the Google Java Style Guide that is directly in
> > > conflict just in case.
> > >
> > > I'm not proposing we rigidly and blindly follow this Coding Standard.
> We
> > > can extend or even supersede portions of the adopted Coding Standard
> with
> > > our own Addendum. The Coding Standard Addendum would exist on the
> Apache
> > > Geode Wiki to define Geode-specific rules or recommendations. What I'd
> > like
> > > to see happen is for us to use the SEI CERT Coding Standard for Java
> as a
> > > starting point for our own Coding Standard. The resulting Coding
> Standard
> > > for Geode can be as static or as living and evolving as we wish.
> > >
> > > The Coding Standard can then provide helpful guidance in how we reshape
> > > some of the Geode code base that is in greater need of refactoring. It
> > > would also help guide us from following poor examples in the current
> code
> > > base when introducing new code.
> > >
> > > [1] https://cwiki.apache.org/confluence/display/GEODE/Code+Style+Guide
> > > [2] https://google.github.io/styleguide/javaguide.html
> > > [3]
> > >
> > >
> >
> https://wiki.sei.cmu.edu/confluence/display/seccode/SEI+CERT+Coding+Standards
> > > [4]
> > >
> > >
> >
> https://wiki.sei.cmu.edu/confluence/display/java/SEI+CERT+Oracle+Coding+Standard+for+Java
> > >
> >
>
Re: [DISCUSS] Adoption of a Coding Standard
Posted by Kirk Lund <kl...@apache.org>.
Java is complicated and Apache Geode is complicated, hence it's a large
Coding Standard. *Effective Java* is similarly *large* if you compare it to
the *Google Java Style Guide*.
The "*rules*" are "*guidelines*" -- I think you're being too literal. Also,
please remember what I said:
I'm not proposing we rigidly and blindly follow this Coding Standard. We
> can extend or even supersede portions of the adopted Coding Standard with
> our own Addendum. The Coding Standard Addendum would exist on the Apache
> Geode Wiki to define Geode-specific rules or recommendations. What I'd like
> to see happen is for us to use the SEI CERT Coding Standard for Java as a
> starting point for our own Coding Standard. The resulting Coding Standard
> for Geode can be as static or as living and evolving as we wish.
>
Is there an entry in the Coding Standard's Rules section that you feel is
irrelevant or incorrect? Please pick an example with a link to it so we can
discuss it.
PS: There aren't any other Coding Standards that I would personally write
or recommend.
On Mon, Jun 24, 2019 at 2:50 PM Alexander Murmann <am...@apache.org>
wrote:
> Hi Kirk,
>
> I think having a coding standard that goes beyond a formatting style guide
> is a great idea. There are many interesting things in the SEI CERT
> standard. However, it's also massive. I see 13 rules just about methods.
> Yet some guidelines that would be most important to me like limiting method
> length and number of parameters are missing.
>
> I wonder if we might be better off taking the rules we like from SEI CERT,
> adding our own and aiming for a much smaller set of guidelines. I'd hope
> for something like a one-pager. If it gets much longer than that, it
> becomes burdensome to read for newcomers and we want to make sure they can
> quickly take in what's most important.
>
> I also prefer "guidelines" over "rules". I'd like to have a discussion if
> someone is not following a guideline, rather than creating the impression
> that all rules must be followed, no matter what the circumstances are.
>
>
> On Mon, Jun 24, 2019 at 2:16 PM Kirk Lund <kl...@apache.org> wrote:
>
> > Apache Geode has a Code Style Guide [1] which is currently defined as
> > following the Google Java Style Guide [2]. This style guide is a good
> > starting point, but it deals primarily with formatting of code and is a
> > fairly dated and static document that doesn't evolve much.
> >
> > I'd like to propose that the Geode dev community adopt a Coding Standard
> in
> > addition to the Style Guide. Specifically, I believe that having our
> > community follow the SEI CERT Coding Standard [3] for Java [4] would
> > benefit us greatly. There are also Coding Standards for C and C++ that we
> > could consider if we decide to use the one for Java.
> >
> > SEI CERT Coding Standards are completely documented on their wiki which
> is
> > open to having anyone join and become involved in their community. They
> are
> > also available in book form (including on amazon.com).
> >
> > From what I've studied, I believe the Coding Standard and Google Java
> Style
> > Guide will be compatible, but we could decide that the Coding Standard
> > supersedes anything in the Google Java Style Guide that is directly in
> > conflict just in case.
> >
> > I'm not proposing we rigidly and blindly follow this Coding Standard. We
> > can extend or even supersede portions of the adopted Coding Standard with
> > our own Addendum. The Coding Standard Addendum would exist on the Apache
> > Geode Wiki to define Geode-specific rules or recommendations. What I'd
> like
> > to see happen is for us to use the SEI CERT Coding Standard for Java as a
> > starting point for our own Coding Standard. The resulting Coding Standard
> > for Geode can be as static or as living and evolving as we wish.
> >
> > The Coding Standard can then provide helpful guidance in how we reshape
> > some of the Geode code base that is in greater need of refactoring. It
> > would also help guide us from following poor examples in the current code
> > base when introducing new code.
> >
> > [1] https://cwiki.apache.org/confluence/display/GEODE/Code+Style+Guide
> > [2] https://google.github.io/styleguide/javaguide.html
> > [3]
> >
> >
> https://wiki.sei.cmu.edu/confluence/display/seccode/SEI+CERT+Coding+Standards
> > [4]
> >
> >
> https://wiki.sei.cmu.edu/confluence/display/java/SEI+CERT+Oracle+Coding+Standard+for+Java
> >
>
Re: [DISCUSS] Adoption of a Coding Standard
Posted by Alexander Murmann <am...@apache.org>.
Hi Kirk,
I think having a coding standard that goes beyond a formatting style guide
is a great idea. There are many interesting things in the SEI CERT
standard. However, it's also massive. I see 13 rules just about methods.
Yet some guidelines that would be most important to me like limiting method
length and number of parameters are missing.
I wonder if we might be better off taking the rules we like from SEI CERT,
adding our own and aiming for a much smaller set of guidelines. I'd hope
for something like a one-pager. If it gets much longer than that, it
becomes burdensome to read for newcomers and we want to make sure they can
quickly take in what's most important.
I also prefer "guidelines" over "rules". I'd like to have a discussion if
someone is not following a guideline, rather than creating the impression
that all rules must be followed, no matter what the circumstances are.
On Mon, Jun 24, 2019 at 2:16 PM Kirk Lund <kl...@apache.org> wrote:
> Apache Geode has a Code Style Guide [1] which is currently defined as
> following the Google Java Style Guide [2]. This style guide is a good
> starting point, but it deals primarily with formatting of code and is a
> fairly dated and static document that doesn't evolve much.
>
> I'd like to propose that the Geode dev community adopt a Coding Standard in
> addition to the Style Guide. Specifically, I believe that having our
> community follow the SEI CERT Coding Standard [3] for Java [4] would
> benefit us greatly. There are also Coding Standards for C and C++ that we
> could consider if we decide to use the one for Java.
>
> SEI CERT Coding Standards are completely documented on their wiki which is
> open to having anyone join and become involved in their community. They are
> also available in book form (including on amazon.com).
>
> From what I've studied, I believe the Coding Standard and Google Java Style
> Guide will be compatible, but we could decide that the Coding Standard
> supersedes anything in the Google Java Style Guide that is directly in
> conflict just in case.
>
> I'm not proposing we rigidly and blindly follow this Coding Standard. We
> can extend or even supersede portions of the adopted Coding Standard with
> our own Addendum. The Coding Standard Addendum would exist on the Apache
> Geode Wiki to define Geode-specific rules or recommendations. What I'd like
> to see happen is for us to use the SEI CERT Coding Standard for Java as a
> starting point for our own Coding Standard. The resulting Coding Standard
> for Geode can be as static or as living and evolving as we wish.
>
> The Coding Standard can then provide helpful guidance in how we reshape
> some of the Geode code base that is in greater need of refactoring. It
> would also help guide us from following poor examples in the current code
> base when introducing new code.
>
> [1] https://cwiki.apache.org/confluence/display/GEODE/Code+Style+Guide
> [2] https://google.github.io/styleguide/javaguide.html
> [3]
>
> https://wiki.sei.cmu.edu/confluence/display/seccode/SEI+CERT+Coding+Standards
> [4]
>
> https://wiki.sei.cmu.edu/confluence/display/java/SEI+CERT+Oracle+Coding+Standard+for+Java
>