| 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? (arjan tijms)
------------------------------------------------------------ ----------
Message: 1
Date: Tue, 10 Apr 2018 07:35:43 +0100
From: arjan tijms <arjan.tijms@xxxxxxxxx>
To: EE4J community discussions <ee4j-community@xxxxxxxxxxx>
Subject: Re: [ee4j-community] EE4J code conventions?
Message-ID:
<CAE=-AhCWzLMs1zZTF+myd=wYRRO0xyGFkp3vXg0yckzrs2_5sQ@mail. >gmail.com
Content-Type: text/plain; charset="utf-8"
It?s also convenient to be able to point new contributors to a document
that says which style is being used.
Definitely should not fail builds because of a bracket on a wrong line.
On Tuesday, April 10, 2018, Ondrej Mih?lyi <ondrej.mihalyi@xxxxxxxxxxx>
wrote:
> -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.html
>> Use
>> > 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@redhat.com >> 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@xxxxxxxxxxxxxxx>> 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@eclipse.org
>> > >> <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
>> *********************************************
>>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://dev.eclipse.org/mailman/private/ee4j- >community/attachments/ 20180410/8cdfe0ba/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 53
*********************************************