Java coding guidelines

Java coding guidelines

adidas Java coding guidelines are based on Google Java Style Guide with minor customization.

Structure of Java source file

A source file must always have the following structure (in given order), with one empty line between them:

* Copyright notice

* Package definition

* Import statements (zero or more)

* Class API documentation comment

* Class code

    - Variables (static, then object, also includes enums)

    - Constructors

    - Methods

        - Functional methods

        - Getters / setters / delegates

        - Inner classes

Code style

Indentation

• Do not use tabs, use plus 2 spaces.
  • Continuation lines use plus 4 spaces.

Whitespaces

• Separating any reserved word if, else , for or catch from any open/close parenthesis (/) or brace {/}.
• Around of any binary or ternary operator.
• Around colon : in a for statement.
• Around arrow -> in a lambda expression.

Braces

We follow the K&R variant: 1TBS.

/* Correct use */
if (y > 1) {
  increase(y);
} else {
  decrease(y);
}

/* Incorrect use */
if (y > 1)
{
  increase(y);
}
else
{
  decrease(y);
}

/* Incorrect use */
if (y > 1) increase(y);
else decrease(y);

Empty blocks

/* Correct use */
void doNothing() { }

/* Incorrect use */
void doNothing() {
}

100 Column limit

We have to follow the limit of 100 character per line taking into account the next exceptions:

• Package and import statements.

Chained methods

/* Correct use */
List<Client> clients = new ArrayList<Client>()
  .add(new Client("John"))
  .add(new Client ("Jean"))
  .add(new Client ("Mark"));

/* Incorrect use */
List<Client> clients = new ArrayList<Client> ().add(new Client("John"))
  .add(new Client ("Jean")).add(new Client ("Mark"));

Name convention

Naming rule	Format
Package	lowercase, in case a package contains more than one word, just the concatenation of them in lowercase, without underscore.
Constants	UPPER_SNAKE
Variables	lowerCamelCase
Class	UpperCamelCase

Comments

It covers only comments in the code , there is a specific section related with Javadoc.

Comment style

Find below examples about the different ways accepted to comment the code.

/*
 * This is a multiline comment.
 */

/* Inline comment */

// Inline comment.

Javadoc

Formatting

Javadoc is mandatory for every public class and every public or protected method part of this class. The general formatting of Javadoc block is the detailed below.

/**
 * Writting here multiple lines of Javadoc text.
 *
 * <p>Example of a second paragraph.</p>
 *
 * @param key The value key.
 * @param value The value sample.
 * @return The absolute value.
 * @throws CustomException if the value does not exist.
 */

Paragraphs

Each paragraphs contained in a Javadoc text have to start with <p> just before the first word.

Block tags

The use of any of the standard block tags should be done in the next order @param as many occurrences as parameters in order, @return and @throws. After them, it is mandatory to add a description.

Good Practices

Exceptions

• Code must not contain empty catch blocks, only in some special cases is allowed to keep a catch block empty and it must be documented properly justifying it.
• A proper exception hierarchy must be present.

Override

Mark a method with the @override annotation whenever you are overriding a method.

• It will increase the readability of the code.
• The compiler will check that method in the parent class. It can help the developers to avoid mistakes such as wrong parameter types or method name.

Links of interest

• Google Java Style Guide.
• Javadoc.