Java Coding Standard

⭐️⭐️ Abbreviations and acronyms should not be uppercase when used as a part of a name.

exportHtmlSource();
openDvdPlayer();

exportHTMLSource();
openDVDPlayer();

⭐️⭐️ Variables with a large scope should have long names, variables with a small scope can have short names.

Scratch variables used for temporary storage or indices can be kept short. A programmer reading such variables should be able to assume that its value is not used outside a few lines of code. Common scratch variables for integers are i, j, k, m, n and for characters c and d.

Rationale: When the scope is small, the reader does not have to remember it for long.

⭐️⭐️ Plural form should be used on names representing a collection of objects.

Collection<Point> points;
int[] values;

Rationale: Enhances readability since the name gives the user an immediate clue of the type of the variable and the operations that can be performed on its elements. One space character after the variable type is enough to obtain clarity.

⭐️⭐️ Associated constants (final variables) should be prefixed by a common type name.

final int COLOR_RED   = 1;
final int COLOR_GREEN = 2;
final int COLOR_BLUE  = 3;

Rationale: This indicates that the constants belong together, and make them appear together when sorted alphabetically.

⭐️⭐️ Place line break to improve readability

When wrapping lines, the main objective is to improve readability. Do not always accept the auto-formatting suggested by the IDE.

In general:

• Break after a comma.

• Break before an operator. This also applies to the following "operator-like" symbols: the dot separator ., the ampersand in type bounds <T extends Foo & Bar>, and the pipe in catch blocks catch (FooException | BarException e)

totalSum = a + b + c
        + d + e;
setText("Long line split"
        + "into two parts.");
method(param1,
        object.method()
                .method2(),
        param3);

• A method or constructor name stays attached to the open parenthesis ( that follows it.

someMethodWithVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongName(
        int anArg, Object anotherArg);

someMethodWithVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongName
        (int anArg, Object anotherArg);

• Prefer higher-level breaks to lower-level breaks. In the example below, the first is preferred, since the break occurs outside the parenthesized expression, which is at a higher level.

longName1 = longName2 * (longName3 + longName4 - longName5)
        + 4 * longname6

longName1 = longName2 * (longName3 + longName4
        - longName5) + 4 * longname6;

• Here are two acceptable ways to format ternary expressions:

alpha = (aLongBooleanExpression) ? beta : gamma;
alpha = (aLongBooleanExpression)
        ? beta
        : gamma;

⭐️⭐️ White space within a statement

It is difficult to give a complete list of the suggested use of whitespace in Java code. The examples below however should give a general idea of the intentions.

Rationale: Makes the individual components of the statements stand out and enhances readability.

⭐️⭐️ Logical units within a block should be separated by one blank line.

// Create a new identity matrix
Matrix4x4 matrix = new Matrix4x4();

// Precompute angles for efficiency
double cosAngle = Math.cos(angle);
double sinAngle = Math.sin(angle);

// Specify matrix as a rotation transformation
matrix.setElement(1, 1,  cosAngle);
matrix.setElement(1, 2,  sinAngle);
matrix.setElement(2, 1, -sinAngle);
matrix.setElement(2, 2,  cosAngle);

// Apply rotation
transformation.multiply(matrix);

Rationale: Enhances readability by introducing white space between logical units. Each block is often introduced by a comment as indicated in the example above.

⭐️⭐️⭐️ Put related classes in a single package.

Package together the classes that are related. For example in Java, the classes related to file writing is grouped in the package java.io and the classes which handle lists, maps etc are grouped in java.util package.

⭐️⭐️ The ordering of import statements must be consistent.

Rationale: A consistent ordering of import statements makes it easier to browse the list and determine the dependencies when there are many imports.

import static org.junit.Assert.assertEquals;
import static org.junit.Assert.assertTrue;

import java.io.File;
import java.io.IOException;

import javax.xml.bind.JAXBContext;
import javax.xml.bind.JAXBException;

import org.loadui.testfx.GuiTest;
import org.testfx.api.FxToolkit;

import com.google.common.io.Files;

import javafx.geometry.Bounds;
import javafx.geometry.Point2D;
import junit.framework.AssertionFailedError;

IDEs have support for auto-ordering import statements. However, note that the default orderings of different IDEs are not always the same. It is recommended that you and your team use the same IDE and stick to a consistent ordering.

Classes and Interfaces

⭐️⭐️⭐️ Class and Interface declarations should be organized in the following manner:

1. Class/Interface documentation (Comments)
2. class or interface statement
3. Class (static) variables in the order public, protected, package (no access modifier), private
4. Instance variables in the order public, protected, package (no access modifier), private
5. Constructors
6. Methods (no specific order)

Rationale: Make code easy to navigate by making the location of each class element predictable.

Methods

⭐️⭐️⭐️ Method modifiers should be given in the following order:

<access> static abstract synchronized <unusual> final native

<access> = public | protected | private
<unusual> = volatile | transient

The <access> modifier (if present) must be the first modifier.

public static double square(double a);

static public double square(double a);

Rationale: The most important point here is to keep the access modifier as the first modifier. The order is less important for the other modifiers , but it make sense to have a fixed convention.

Variables

⭐️⭐️ Variables should be initialized where they are declared and they should be declared in the smallest scope possible.

int sum = 0;
for (int i = 0; i < 10; i++) {
    for (int j = 0; j < 10; j++) {
        sum += i * j;
    }
}

int i, j, sum;
sum = 0;
for (i = 0; i < 10; i++) {
    for (j = 0; j < 10; j++) {
        sum += i * j;
    }
}

Rationale: This ensures that variables are valid at any time. Sometimes it is impossible to initialize a variable to a valid value where it is declared. In these cases it should be left uninitialized rather than initialized to some phony value.

⭐️⭐️ Class variables should never be declared public.

Bad

public class Foo{

   public int bar;

}

Rationale: The concept of Java information hiding and encapsulation is violated by public variables. Use private variables and access functions instead. One exception to this rule is when the class is essentially a data structure, with no behavior. In this case it is appropriate to make the class' instance variables public.

⭐️⭐️⭐️ Avoid unnecessary use of this with fields.

Use the this keyword only when a field is shadowed by a method or constructor parameter.

public User(String name) {
    this.name = name;
    ...
}

public User(String name) {
    // 'id' is not shadowed by any method parameters
    this.id = User.getNewId();
    ...
}

Rationale: to reduce unnecessary noise.

⭐️⭐️ Write descriptive header comments for all public classes/methods.

You MUST write header comments for all classes, public methods.

Rationale: public method are meant to be used by others and the users should not be forced to read the code of the method to understand its exact behavior. The code, even if it is self-explanatory, can only tell the reader HOW the code works, not WHAT the code is supposed to do.

⭐️⭐️⭐️ All non-trivial private methods should carry header comments.

Rationale: Writing header comments will hep novice programmers to self-detect abstraction problems. e.g. If it is hard to describe the method succinctly, there is something wrong with the method abstraction.

⭐️⭐️ Javadoc comments should have the following form:

/**
 * Returns lateral location of the specified position.
 * If the position is unset, NaN is returned.
 *
 * @param x  X coordinate of position.
 * @param y Y coordinate of position.
 * @param zone Zone of position.
 * @return Lateral location.
 * @throws IllegalArgumentException  If zone is <= 0.
 */
public double computeLocation(double x, double y, int zone)
    throws IllegalArgumentException {
  ...
}

Note in particular:

• The opening /** on a separate line
• Write the first sentence as a short summary of the method, as Javadoc automatically places it in the method summary table (and index).
  • In method header comments, the first sentence should start in the form Returns ..., Sends ..., Adds ... (not Return or Returnning etc.)
• Subsequent * is aligned with the first one
• Space after each *
• Empty line between description and parameter section
• Punctuation behind each parameter description -No blank line between the documentation block and the method/class

Javadoc of class members can be specified on a single line as follows:

/** Number of connections to this database */
private int connectionCount;