Re: [ee4j-community] EE4J code conventions?

["Markus KARG" <markus@xxxxxxxxxxxxxxx>]

Can you please also put on the PMC's table that we are at the Eclipse Foundation here, and that Eclipse IDE by default has a different style to what Arjan proposed, and that committers might not be happy with more dictates from the PMC, and that other Eclipse projects also do not share the proposed style…? There is no essential force to have a dictated formatting, so why restrict the commiter's freedom?

-Markus

 

From: ee4j-community-bounces@xxxxxxxxxxx [mailto:ee4j-community-bounces@xxxxxxxxxxx] On Behalf Of Ivar Grimstad
Sent: Montag, 9. April 2018 06:35
To: EE4J community discussions
Subject: Re: [ee4j-community] EE4J code conventions?

 

I will add the topic to our agenda for the next PMC meeting.

 

Ivar

On Mon, 9 Apr 2018, 03:51 Mike Milinkovich, <mike.milinkovich@xxxxxxxxxxxxxxxxxxxxxx> wrote:

 

Personally, I have no skin in this game at all.  But I will point out that this is a discussion/decision for the PMC.

 

Mike Milinkovich

+1.613.220.3223

mike.milinkovich@xxxxxxxxxxxxxxxxxxxxxx

On Apr 8, 2018, at 6:08 PM, arjan tijms <arjan.tijms@xxxxxxxxx> wrote:

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

--

Java Champion, JCP EC/EG Member, EE4J PMC, JUG Leader