| Re: [ee4j-community] EE4J code conventions? |
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? (reza_rahman)
------------------------------------------------------------ ----------
Message: 1
Date: Mon, 09 Apr 2018 09:40:12 -0400
From: reza_rahman <reza_rahman@xxxxxxxxx>
To: EE4J community discussions <ee4j-community@xxxxxxxxxxx>
Subject: Re: [ee4j-community] EE4J code conventions?
Message-ID: <mailman.168.1523281216.3433.ee4j-community@xxxxxxxxxxx >
Content-Type: text/plain; charset="utf-8"
I do agree with Arjan that we need the equivalent of what the Java EE umbrella EG and specification leads did or should have done to guarantee some consistency across Java EE specifications.
I am still a bit hazy as to how the various EE4J committees are supposed to work, but perhaps this sort of thing is now the role of the PMC?
Sent via the Samsung Galaxy S7, an AT&T 4G LTE smartphone
-------- Original message --------From: arjan tijms <arjan.tijms@xxxxxxxxx> Date: 4/9/18 9:11 AM (GMT-05:00) To: EE4J community discussions <ee4j-community@xxxxxxxxxxx> Subject: Re: [ee4j-community] EE4J code conventions?
Hi,
On Mon, Apr 9, 2018 at 1:58 PM, Kevin Sutter <sutter@xxxxxxxxxx> wrote:
+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.
While the goal is to have code conventions, and having them at the project level is definitely better than having none at all, I do wonder why we would even want different conventions per project?
I mean, why would we actively want to steer towards say Mojarra using?
public void foo(){}
and say Soteria using:
public void foo() {}
One approach is not better or worse than the other, so it's unlikely to be a matter of saying that any of the bracing styles is more suitable to either project.
In Java EE the umbrella spec didn't give that much steering as compared to say Java SE, or even though it's a different kind of setup, Spring projects or even Jboss projects. As a result we got quite a number of differences that shouldn't have to be there. Perhaps with Jakarta EE there could be somewhat more steering, so at least the Jakarta EE APIs and EE4J implementations have a somewhat consistent feel.
There's not just the code style, but also the tools used for documentation, tools used for (TCK) tests, tools used for building ?and with respect to the APIs a number of architecture guidelines or rules for naming, CDI usage, and what have you.
Kind regards,
Arjan
?
---------------------------------------------------
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.ioit 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@eclipse.orgTo 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=
_______________________________________________
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/88b62f4d/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 37
*********************************************