| Re: [ee4j-community] EE4J code conventions? |
-1 to enforcing code style
+1 to monitoring code quality and even enforce some metrics (e.g. method length)
Style is a matter of taste and I've never saw that enforcing it really worked. Rarely it improves the code readability and often slows everybody down with a lot of broken builds just because of a bracket on a different line.
If qe decide to enforce style, then absolute basics which bring the most value (e.g. no tabs but spaces, no if statements without brackets, etc)
Code quality is more important for keeping the code readable and maintainable but I would also enforce only a handful of basic and most important rules.
Ondro
From: ee4j-community-bounces@eclipse.org <ee4j-community-bounces@eclipse.org > on behalf of Werner Keil <werner.keil@xxxxxxxxx>
Sent: Monday, April 9, 2018 11:17:18 PM
To: EE4J community discussions
Subject: Re: [ee4j-community] EE4J code conventions?I would say from a point of potential users of Jakarta EE it is far less important if the braces close in the same line, developers use the "Hungarian notation" or not, but a certain level of code quality should be displayed if Multi Billion Dollar companies are supposed to use and trust it.
As Bill mentioned, OpenJDK failed to implement a common coding guideline. And based on SonarCloud it also failed quite miserable when it comes to code quality and avoiding code smells or technical debt: https://sonarcloud.io/dashboard?id=openjdk (this was last analyzed in October 2017 shortly after Java 9 went Final)
A small number of Eclipse projects like Eclipse Collections also uses that public SonarCloud instance:https://sonarcloud.io/explore/projects?search=eclipse And compared to OpenJDK it looks much better. Whether each individual project or cumulated for Jakarta EE, it would be very beneficial to have that for key components of EE4J / Jakarta EE
Werner
On Mon, Apr 9, 2018 at 10:59 PM, <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? (Werner Keil)
------------------------------------------------------------ ----------
Message: 1
Date: Mon, 9 Apr 2018 22:59:40 +0200
From: Werner Keil <werner.keil@xxxxxxxxx>
To: EE4J community discussions <ee4j-community@xxxxxxxxxxx>
Subject: Re: [ee4j-community] EE4J code conventions?
Message-ID:
<CAAGawe014cdmriPQrHi5QHoztqhixYiVksKorbfBYDbETxA4mw@xxxxxxx >ail.com
Content-Type: text/plain; charset="utf-8"
Bill,
I guess if this draft was created in OpenJDK it may be used and needs no
clearance by Oracle Legal, etc. correct?
Given that what so far exists in Eclipse Wiki is not much more than the
Copyright notice paragraph in a slightly different way.
Sharing something like it in a wiki sounds good.
How many projects under the Java EE umbrella with Oracle being Spec Leads
do you remember doing what they want regardless of guidance by the Umbrella
Spec Leads or Oracle/Sun Java architects?
Werner
On Mon, Apr 9, 2018 at 10:44 PM, <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? (Bill Shannon)
> 2. Re: EE4J code conventions? (Lukas Jungmann)
>
>
> ------------------------------------------------------------ ----------
>
> Message: 1
> Date: Mon, 9 Apr 2018 13:32:46 -0700
> From: Bill Shannon <bill.shannon@xxxxxxxxxx>
> To: EE4J community discussions <ee4j-community@xxxxxxxxxxx>, arjan
> tijms <arjan.tijms@xxxxxxxxx>
> Subject: Re: [ee4j-community] EE4J code conventions?
> Message-ID: <836e9474-133b-c395-2186-2de6bceced50@xxxxxxxxxx >
> Content-Type: text/plain; charset="utf-8"
>
> -100
>
> Coding style and conventions are very important, but based on decades of
> experience dealing with these issues, you're going to waste a lot of time
> arguing about the details and in the end many people are not going to
> agree and
> are going to do whatever they want.? Fighting about this is just not
> important
> and doesn't help the community.? Lots of people like the idea of having
> code
> conventions, but getting lots of people to agree on a specific coding
> style is
> very difficult.
>
> If you want to recommend some guidelines that aren't enforced, then start
> with
> what already exists.? If you don't like the existing guidelines, then you
> understand why this is a hard problem.? The OpenJDK community already went
> through this and the closest they got was this draft
> <http://cr.openjdk.java.net/%7Ealundblad/styleguide/index-v6 >.? Use.html
> that.
>
> An individual project might want to enforce stricter rules or have
> different
> conventions.? That's fine.? But give up trying to enforce something for
> all of EE4J.
>
> This is a bike shed that we don't need to paint.
>
>
> arjan tijms wrote on 04/ 8/18 03:08 PM:
> > 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
>
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL: <https://dev.eclipse.org/mailman/private/ee4j-community/ attachments/
> 20180409/29db1977/attachment.html>
>
> ------------------------------
>
> Message: 2
> Date: Mon, 9 Apr 2018 22:44:34 +0200
> From: Lukas Jungmann <lukas.jungmann@xxxxxxxxxx>
> To: ee4j-community@xxxxxxxxxxx
> Subject: Re: [ee4j-community] EE4J code conventions?
> Message-ID: <5b29c4c1-54dc-8d8b-aec2-041533ec2013@xxxxxxxxxx >
> Content-Type: text/plain; charset=utf-8; format=flowed
>
> On 4/9/18 9:46 PM, arjan tijms wrote:
> > Hi,
> >
> > On Monday, April 9, 2018, Jason Greene <jason.greene@xxxxxxxxxx
> > <mailto:jason.greene@xxxxxxxxxm >> wrote:
> >
> > The other factor to keep in mind is there is going to be gigantic
> > source import from a bunch of different projects that each may have
> > followed different conventions.
> >
> >
> > Many have established communities and may have strong opinions about
> > this.
> >
> >
> > You are right that if it would be totally different projects from
> > different origins that would be a major issue, but in this case aren?t
> > all the transferred projects the RI projects from Oracle?
>
> yes and no. EclipseLink while being among those being transferred is
> under EF control since 2007 and its roots dates back to 1996 (if we are
> talking only about its Java version), with Oracle and IBM being most
> active committers there during last say ~5 years
>
> >
> > They already have essentially the Sun/Eclipse conventions with spaces.
> > At least, as far as I know not a single one of the former Oracle
> > projects use tabs. One project that does uses tabs is OmniFaces btw ;)
>
> there were parts which were using Tabs; there were also files which were
> using mixed line-endings (yeah believe it or not there really were files
> where some lines ended with LF and others with CR/LF - don't ask me how
> that could happen) - both of these "issues" were "fixed" few years ago
> and that was the only (history destructive) code-formatting change we
> were willing to make.
>
> thanks,
> --lukas
>
> >
> > One important thing to note is that the proposal in the opening post is
> > just that, a proposal. The idea was that a convention would be
> > established by committers from all EE4J modules (projects), which
> > however are not rarely the same people.
> >
> > Kind regards,
> > Arjan
> >
> >
> >> On Apr 9, 2018, at 12:54 PM, Markus KARG <markus@xxxxxxxxxxxxxxx
> >> <mailto:markus@headcrashing.eu >> wrote:
> >>
> >> You assumption is wrong. The open source project is not EE4J. EE4J
> >> is only a common organization within the EF, and the projects are
> >> self-governing. Believe Mike, he should know best? ;-)____
> >>
> >> __ __
> >>
> >> BTW, I am contributing to dozens of open source projects, none of
> >> them share formatting rules, and never had a problem with that.
> >> ;-)____
> >>
> >> __ __
> >>
> >> Anyways, the PMC will be wise enough to decide.____
> >>
> >> __ __
> >>
> >> -Markus____
> >>
> >> __ __
> >>
> >> __ __
> >>
> >> *From:*ee4j-community-bounces@xxxxxxxxxxx
> >> <mailto:ee4j-community-bounces@xxxxxxxxxxx >
> >> [mailto:ee4j-community-bounces@xxxxxxxxxxx
> >> <mailto:ee4j-community-bounces@xxxxxxxxxxx >] *On Behalf Of *arjan
> >> tijms
> >> *Sent:* Montag, 9. April 2018 16:42
> >> *To:* EE4J community discussions
> >> *Subject:* Re: [ee4j-community] EE4J code conventions?____
> >>
> >> __ __
> >>
> >> Hi,____
> >>
> >> __ __
> >>
> >> On Mon, Apr 9, 2018 at 2:18 PM, Mike Milinkovich
> >> <mike.milinkovich@eclipse-foundation.org
> >> <mailto:mike.milinkovich@eclipse-foundation.org >> wrote:____
> >>
> >> Because Eclipse Foundation open source projects are self-governing
> >> meritocracies, and we don't tell them what to do. Ultimately, it
> >> is the committers who would need to do the work, and I don't think
> >> any of us get to tell them how to spend their time. ____
> >>
> >> __ __
> >>
> >> I can see that, but in this case the open source project would be
> >> EE4J, with all the concrete projects being sub-projects of that,
> >> not totally independent projects.____
> >>
> >> __ __
> >>
> >> I know it's not totally the same, but suppose that in Mojarra I'm
> >> responsible for the component package, while say Bauke works on
> >> the websocket package. Naturally we'd want a single code
> >> convention for Mojarra, not one per package.____
> >>
> >> __ __
> >>
> >> Now when seeing EE4J as one project, the question might be whether
> >> it really makes sense to have separate code conventions per
> >> 'module', but I guess it also depends on how much one sees EE4J as
> >> 1 framework, or more as a set of somewhat cobbled together
> >> independent projects. I personally would lean more to the former,
> >> but I know historically it has been more of the latter.____
> >>
> >> __ __
> >>
> >> There is the issue though that in EE4J we do have an amount of
> >> committers that are active on many EE4J projects, and the Jakarta
> >> EE/Eclipse process might make that easier than before with Java EE
> >> and the JCP.____
> >>
> >> __ __
> >>
> >> For those people specifically it would perhaps not be entirely
> >> optimal having to change between conventions all the time, say if
> >> Mojarra decided to got for tabs, but Soteria would go for spaces.
> >> It also would make building and sharing build knowledge more
> >> difficult if for example Mojarra switched over the Gradle, but
> >> Soteria kept using Maven, and then Jersey switched over to Ant,
> >> with Grizzly going to Make.____
> >>
> >> __ __
> >>
> >> Kind regards,____
> >>
> >> Arjan____
> >>
> >> __ __
> >>
> >> __ __
> >>
> >> __ __
> >>
> >> __ __
> >>
> >> __ __
> >>
> >> __ __
> >>
> >> ____
> >>
> >>
> >> I'm not saying that this is an unreasonable idea. But
> >> generally speaking open source projects don't respond well to
> >> being ordered about. Ivar has already said that he'll raise it
> >> with the PMC. Let's wait and see how that plays out.
> >>
> >> ____
> >>
> >>
> >> _______________________________________________
> >> ee4j-community mailing list
> >> ee4j-community@xxxxxxxxxxx <mailto:ee4j-community@eclipse.org >
> >> 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 <mailto:ee4j-community@eclipse.org >
> >> 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
> >
>
>
> ------------------------------
>
> _______________________________________________
> 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 48
> *********************************************
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://dev.eclipse.org/mailman/private/ee4j-community/ >attachments/20180409/4f1f3dcf/ 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 49
*********************************************