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.
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