| Re: [ee4j-community] EE4J code conventions? |
Werner
Send ee4j-community mailing list submissions to
ee4j-community@xxxxxxxxxxx
To subscribe or unsubscribe via the World Wide Web, visit
https://dev.eclipse.org/mailman/listinfo/ee4j- community
or, via email, send a message with subject or body 'help' to
ee4j-community-request@eclipse.org
You can reach the person managing the list at
ee4j-community-owner@eclipse.org
When replying, please edit your Subject line so it is more specific
than "Re: Contents of ee4j-community digest..."
Today's Topics:
1. Re: EE4J code conventions? (Werner Keil)
2. Re: EE4J code conventions? (Kevin Sutter)
------------------------------------------------------------ ----------
Message: 1
Date: Mon, 9 Apr 2018 11:55:05 +0200
From: Werner Keil <werner.keil@xxxxxxxxx>
To: EE4J community discussions <ee4j-community@xxxxxxxxxxx>
Subject: Re: [ee4j-community] EE4J code conventions?
Message-ID:
<CAAGawe1dDdb9C90spXBvZBpeJLMi_ dq-QGvtF0zqfuX3=8O5vA@mail. gmail.com >
Content-Type: text/plain; charset="utf-8"
Sounds like a good idea. And at least for (somewhat obvious) Eclipse
formatters there is also a Maven plugin allowing to apply them via a build
job or a particular profile as well as check during the build if desired.
Werner
On Mon, Apr 9, 2018 at 11:29 AM, <ee4j-community-request@eclipse.org > wrote:
> Send ee4j-community mailing list submissions to
> ee4j-community@xxxxxxxxxxx
>
> To subscribe or unsubscribe via the World Wide Web, visit
> https://dev.eclipse.org/mailman/listinfo/ee4j- community
> or, via email, send a message with subject or body 'help' to
> ee4j-community-request@eclipse.org
>
> You can reach the person managing the list at
> ee4j-community-owner@eclipse.org
>
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of ee4j-community digest..."
>
>
> Today's Topics:
>
> 1. Re: EE4J code conventions? (Alexander Salvanos)
> 2. Re: EE4J code conventions? (Dmitry Kornilov)
>
>
> ------------------------------------------------------------ ----------
>
> Message: 1
> Date: Mon, 9 Apr 2018 09:01:11 +0200
> From: "Alexander Salvanos" <salvanos@xxxxxx>
> To: ee4j-community@xxxxxxxxxxx
> Subject: Re: [ee4j-community] EE4J code conventions?
> Message-ID:
> <trinity-debd6940-7757-4e41-9b1d-edb1eaf6cf9d-
> 1523257271298@3c-app-gmx-bs80>
>
> Content-Type: text/plain; charset="us-ascii"
>
> An HTML attachment was scrubbed...
> URL: <https://dev.eclipse.org/mailman/private/ee4j- community/attachments/
> 20180409/a8fa5d33/attachment.html>
>
> ------------------------------
>
> Message: 2
> Date: Mon, 9 Apr 2018 11:33:10 +0200
> From: Dmitry Kornilov <dmitry.kornilov@xxxxxxxxxx>
> To: EE4J community discussions <ee4j-community@xxxxxxxxxxx>
> Subject: Re: [ee4j-community] EE4J code conventions?
> Message-ID: <BE42B13F-8626-4E10-9AB9-AF50652E9F1F@xxxxxxxxxx >
> Content-Type: text/plain; charset="utf-8"
>
> My 2 cents here is that it should be up to the projects. I agree with a
> general concept of having code conventions, but I don?t like the idea of
> enforcing it to all EE4J projects (it can be recommended though).
> Checkstyle plugin with recommended conventions can be configured in EE4J
> parent pom, which is another 'nice to have' feature.
>
> ? Dmitry
>
> > On 9 Apr 2018, at 09:01, Alexander Salvanos <salvanos@xxxxxx> wrote:
> >
> > +1 for the code convention proposal.
> > Even if most is determined by Sun's old convention, it is a good idea to
> remind committers.
> > What about formatters for Eclipse, IntelliJ etc.?
> >
> > Best,
> > Alex
> >
> >
> > Alexander Salvanos
> > Goebenstr.5
> > D-53113 Bonn
> > Telefon: +49 (151) 24296962
> >
> >
> > Gesendet: Montag, 09. April 2018 um 00:08 Uhr
> > Von: "arjan tijms" <arjan.tijms@xxxxxxxxx>
> > An: "EE4J community discussions" <ee4j-community@xxxxxxxxxxx>
> > Betreff: [ee4j-community] EE4J code conventions?
> > Hi,
> >
> > I wonder if it would be a good idea to define a set of code conventions
> for EE4J going forward.
> >
> > It looks like Oracle never really had one, or at least if there was one
> did not enforce it. Specially the Mojarra code base and the parts of the
> code in GlassFish that implement JACC and JASPIC have a rather inconsistent
> formatting and overal style.
> >
> > My initial proposal would be something along the following lines:
> >
> > Formatting:
> >
> > Eclipse/Sun code conventions with
> > - Spaces only
> > - Indentation size 4 spaces
> > - Maximum line width 160
> > - Maximum width for comments 120
> > - No indent of Javadoc tags
> > - No newline after @param tags
> >
> > As for the Javadoc, the Sun code conventions don't specify these
> directly. There's a separate article from Oracle though that uses examples
> for an highly indented style though, that would be an alternative candidate.
> >
> > The style I'm referring to above seems fairly common and looks like this
> for example:
> >
> > @param a The first parameter. For an optimum result, this should be an
> odd
> > number between 0 and 100.
> >
> >
> > Variable naming style:
> >
> > Based on the advice from Uncle Bob's Clean Code, specifically:
> >
> > -No cryptic abbreviations like c, ta, rx, ct, with the exception of the
> well established i and J in loops
> > -No variable names like ret, rvalue, result etc for variables that are
> returned from methods. Instead, the should be named after what they
> actually return. For example:
> >
> > Bad:
> >
> > public Permissions getCallerPermission(....) {
> > Permissions rvalue;
> > // ton of code
> >
> > return rvalue;
> > }
> >
> > Good:
> >
> > public Permissions getCallerPermissions(....) {
> > Permissions callerPermissions;
> > // ton of code
> >
> > return callerPermissions;
> > }
> >
> > -No Hungarian variations for collections like usrLst, usArray, arrUsers,
> UserCol, etc, and no such variation for elements of the collection like el,
> elm, usrEl, userElem, currentUsr, curUser, userCr, etc. Omit the Hungarian
> and use the element type name directly and the plural of that for the
> collection. For example:
> >
> > Bad:
> >
> > for (User curUsr : colUser) {
> > ...
> > }
> >
> > Good:
> >
> > for (User user : users) {
> > ...
> > }
> >
> >
> > Conditional blocks
> >
> > - Handle the short and fast error case for method parameters early
> instead of the happy path. For example:
> >
> > Bad:
> >
> > public void foo(Bar bar) {
> > if (bar != null) {
> > // lots of code here
> > } else {
> > throw new IllegalStateException("Bar should not be null");
> > }
> > }
> >
> > Good:
> >
> > public void foo(Bar bar) {
> > if (bar == null) {
> > throw new IllegalStateException("Bar should not be null");
> > }
> >
> > // lots of code here
> > }
> >
> > - if/else blocks that return don't need to be if/else blocks. For
> example:
> >
> > Bad:
> >
> > if (foo == something) {
> > return somethingFoo;
> > } else if (foo == somethingElse) {
> > return somethingElseFoo;
> > }
> >
> > Good:
> >
> > if (foo == something) {
> > return somethingFoo;
> > }
> >
> > if (foo == somethingElse) {
> > return somethingElseFoo;
> > }
> >
> >
> > Defaults
> >
> > - Omit initialisation of instance variables to their default values. For
> example:
> >
> > Bad:
> >
> > public class SomeClass {
> > private int someNumber = 0;
> > private Foo someFoo = null;
> > private boolean isFoo = false;
> > }
> >
> > Good:
> >
> > public class SomeClass {
> > private int someNumber;
> > private Foo someFoo;
> > private boolean isFoo;
> > }
> >
> > - Omit using the pubic modifier for interface methods .For example:
> >
> > Bad:
> >
> > public interface MyInterface {
> > public void MyMethod();
> > }
> >
> > Good:
> >
> > public interface MyInterface {
> > void MyMethod();
> > }
> >
> > - Omit unnecessary braces. For example:
> >
> > Bad
> >
> > return (1);
> >
> > Good
> >
> > return 1;
> >
> >
> > A large number of additional code convention rules are contained in the
> well known SonarQube. The default rule set ("the sonar way") is probably a
> good starting point and with sonarcloud.io <http://sonarcloud.io/> it
> would be relatively easy to check each EE4J project. Rules that would be
> specifically good IMHO to pay attention to are the ones that warn for high
> levels of cyclomatic complexity and large classes.
> >
> > Thoughts?
> >
> > Kind regards,
> > Arjan Tijms
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> > _______________________________________________ ee4j-community mailing
> list ee4j-community@xxxxxxxxxxx To change your delivery options, retrieve
> your password, or unsubscribe from this list, visit
> https://dev.eclipse.org/mailman/listinfo/ee4j- <community
> https://dev.eclipse.org/mailman/listinfo/ee4j- community
> >_______________________________________________
> > ee4j-community mailing list
> > ee4j-community@xxxxxxxxxxx
> > To change your delivery options, retrieve your password, or unsubscribe
> from this list, visit
> > https://dev.eclipse.org/mailman/listinfo/ee4j- community
>
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL: <https://dev.eclipse.org/mailman/private/ee4j- community/attachments/
> 20180409/b3142191/attachment.html>
>
> ------------------------------
>
> _______________________________________________
> ee4j-community mailing list
> ee4j-community@xxxxxxxxxxx
> To change your delivery options, retrieve your password, or unsubscribe
> from this list, visit
> https://dev.eclipse.org/mailman/listinfo/ee4j- community
>
>
> End of ee4j-community Digest, Vol 8, Issue 32
> *********************************************
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://dev.eclipse.org/mailman/private/ee4j- >community/attachments/ 20180409/d7829295/attachment. html
------------------------------
Message: 2
Date: Mon, 9 Apr 2018 07:58:13 -0500
From: "Kevin Sutter" <sutter@xxxxxxxxxx>
To: EE4J community discussions <ee4j-community@xxxxxxxxxxx>
Subject: Re: [ee4j-community] EE4J code conventions?
Message-ID:
<OF34AA4258.48D1551F-ON8625826A.00467D0D-8625826A. >00473F27@xxxxxxxx.collabserv. com
Content-Type: text/plain; charset="utf-8"
+1, Dmitry. Coding conventions should be a project-specific requirement,
not an EE4J requirement. EE4J could possibly recommend some coding
conventions, but the requirements should be left up to each individual
project.
---------------------------------------------------
Kevin Sutter
STSM, MicroProfile and Java EE architect
e-mail: sutter@xxxxxxxxxx Twitter: @kwsutter
phone: tl-553-3620 (office), 507-253-3620 (office)
LinkedIn: https://www.linkedin.com/in/kevinwsutter
From: Dmitry Kornilov <dmitry.kornilov@xxxxxxxxxx>
To: EE4J community discussions <ee4j-community@xxxxxxxxxxx>
Date: 04/09/2018 04:29 AM
Subject: Re: [ee4j-community] EE4J code conventions?
Sent by: ee4j-community-bounces@eclipse.org
My 2 cents here is that it should be up to the projects. I agree with a
general concept of having code conventions, but I don?t like the idea of
enforcing it to all EE4J projects (it can be recommended though).
Checkstyle plugin with recommended conventions can be configured in EE4J
parent pom, which is another 'nice to have' feature.
? Dmitry
On 9 Apr 2018, at 09:01, Alexander Salvanos <salvanos@xxxxxx> wrote:
+1 for the code convention proposal.
Even if most is determined by Sun's old convention, it is a good idea to
remind committers.
What about formatters for Eclipse, IntelliJ etc.?
Best,
Alex
Alexander Salvanos
Goebenstr.5
D-53113 Bonn
Telefon: +49 (151) 24296962
Gesendet: Montag, 09. April 2018 um 00:08 Uhr
Von: "arjan tijms" <arjan.tijms@xxxxxxxxx>
An: "EE4J community discussions" <ee4j-community@xxxxxxxxxxx>
Betreff: [ee4j-community] EE4J code conventions?
Hi,
I wonder if it would be a good idea to define a set of code conventions
for EE4J going forward.
It looks like Oracle never really had one, or at least if there was one
did not enforce it. Specially the Mojarra code base and the parts of the
code in GlassFish that implement JACC and JASPIC have a rather
inconsistent formatting and overal style.
My initial proposal would be something along the following lines:
Formatting:
Eclipse/Sun code conventions with
- Spaces only
- Indentation size 4 spaces
- Maximum line width 160
- Maximum width for comments 120
- No indent of Javadoc tags
- No newline after @param tags
As for the Javadoc, the Sun code conventions don't specify these directly.
There's a separate article from Oracle though that uses examples for an
highly indented style though, that would be an alternative candidate.
The style I'm referring to above seems fairly common and looks like this
for example:
@param a The first parameter. For an optimum result, this should be an
odd
number between 0 and 100.
Variable naming style:
Based on the advice from Uncle Bob's Clean Code, specifically:
-No cryptic abbreviations like c, ta, rx, ct, with the exception of the
well established i and J in loops
-No variable names like ret, rvalue, result etc for variables that are
returned from methods. Instead, the should be named after what they
actually return. For example:
Bad:
public Permissions getCallerPermission(....) {
Permissions rvalue;
// ton of code
return rvalue;
}
Good:
public Permissions getCallerPermissions(....) {
Permissions callerPermissions;
// ton of code
return callerPermissions;
}
-No Hungarian variations for collections like usrLst, usArray, arrUsers,
UserCol, etc, and no such variation for elements of the collection like
el, elm, usrEl, userElem, currentUsr, curUser, userCr, etc. Omit the
Hungarian and use the element type name directly and the plural of that
for the collection. For example:
Bad:
for (User curUsr : colUser) {
...
}
Good:
for (User user : users) {
...
}
Conditional blocks
- Handle the short and fast error case for method parameters early instead
of the happy path. For example:
Bad:
public void foo(Bar bar) {
if (bar != null) {
// lots of code here
} else {
throw new IllegalStateException("Bar should not be null");
}
}
Good:
public void foo(Bar bar) {
if (bar == null) {
throw new IllegalStateException("Bar should not be null");
}
// lots of code here
}
- if/else blocks that return don't need to be if/else blocks. For example:
Bad:
if (foo == something) {
return somethingFoo;
} else if (foo == somethingElse) {
return somethingElseFoo;
}
Good:
if (foo == something) {
return somethingFoo;
}
if (foo == somethingElse) {
return somethingElseFoo;
}
Defaults
- Omit initialisation of instance variables to their default values. For
example:
Bad:
public class SomeClass {
private int someNumber = 0;
private Foo someFoo = null;
private boolean isFoo = false;
}
Good:
public class SomeClass {
private int someNumber;
private Foo someFoo;
private boolean isFoo;
}
- Omit using the pubic modifier for interface methods .For example:
Bad:
public interface MyInterface {
public void MyMethod();
}
Good:
public interface MyInterface {
void MyMethod();
}
- Omit unnecessary braces. For example:
Bad
return (1);
Good
return 1;
A large number of additional code convention rules are contained in the
well known SonarQube. The default rule set ("the sonar way") is probably a
good starting point and with sonarcloud.io it would be relatively easy to
check each EE4J project. Rules that would be specifically good IMHO to pay
attention to are the ones that warn for high levels of cyclomatic
complexity and large classes.
Thoughts?
Kind regards,
Arjan Tijms
_______________________________________________ ee4j-community mailing
list ee4j-community@xxxxxxxxxxx To change your delivery options, retrieve
your password, or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/ee4j- community
_______________________________________________
ee4j-community mailing list
ee4j-community@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe
from this list, visit
https://dev.eclipse.org/mailman/listinfo/ee4j- community
_______________________________________________
ee4j-community mailing list
ee4j-community@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe
from this list, visit
https://urldefense.proofpoint.com/v2/url?u=https-3A__dev. eclipse.org_mailman_listinfo_ ee4j-2Dcommunity&d=DwICAg&c= jf_iaSHvJObTbx-siA1ZOg&r= R9dtOS3afYnRUmu_ zogmh0VnVYl2tse_V7QBUA9yr_4&m= rhrpQTevVQ3jegJ7THf4smXOvXA6am ZD_D_oUM9ibsI&s=e6gcswwR_ bZDI97sbJNaTiqVNdz3zzHs7RD0FEV 2Gmo&e=
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://dev.eclipse.org/mailman/private/ee4j- >community/attachments/ 20180409/a44352af/attachment. html
------------------------------
_______________________________________________
ee4j-community mailing list
ee4j-community@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/ee4j- community
End of ee4j-community Digest, Vol 8, Issue 33
*********************************************