This is an internal documentation. There is a good chance you’re looking for something else. See Disclaimer.

Java Guidelines

General

  • Always include curly brackets, even for one-line if statements or for loops.

  • One statement per line. Avoid too long line (make a line break after ~ 120 characters).

  • Avoid the if ternary operator.

  • Each interface has a corresponding unit test named InterfaceName Test.java

  • Strings are concatenated with String.format(...) and not "String1" + "String2".

  • Create lists and sets which are always empty with List.of() and Set.of(). Else use the Guava library to create lists and sets (E.g. ImmutableList.of(1, 2)).

  • Each mock in a test must be verified.

  • A class has the following structure (sorting of the different class elements):

    • Variables:

      • Constants (static final)

      • Injected services

      • Other variables such as mocks in tests

    • Constructors

    • Methods: First public, then protected, and then private methods are defined

Naming

  • Interfaces have no I-prefix. If an interface has only one implementation this class has the suffix Impl (E.g. Interface: PizzaFactory and Implementation PizzaFactoryImpl).

  • Class names are declared in pascal case.

  • Methods and field names are declared in camel case (E.g. getCmsPage()).

  • Constants are declared in uppercase snake case (E.g. private static final int CACHE_SIZE = 100;).

  • Class members are always private and getter/setters are used for interaction.

Parameters and Return Values

  • The @Nullable annotation from the org.jetbrains.annotations package is used. But parameters and return values are not annotated with @NotNull.

  • An alternative to a nullable return value is an optional from Java (not Guava).

  • Parameters are validated if the input is in the expected range. Else an IllegalArgumentException is thrown.

Exception Handling

  • Catch blocks are never empty. At least log the error.

  • Use the logger and not System.{out, err, ...} or Exception#printStrackTrace().

  • Before an exception is thrown the reason should be logged.

  • A method should throw only checked exceptions which are relevant for the caller. Less relevant exceptions, which you do not want to handle yourself, should be wrapped in a general exception.

Documentation

  • Use JavaDoc for documentation

    • Interfaces and methods which are not private have JavaDoc especially if they are in the api / spi package and available in other modules (Exceptions are getters & setters and standard Java beans). The documentation describes the purpose of the class and points out special cases etc.

    • Information about the author (@author) and the creation time (@since) is not relevant in JavaDoc - for this we have a VCS.

    • JavaDoc for methods (except private ones) contains at least (if useful) @throws, @returns, @param.

    • Use the markdown syntax for formatting and not HTML.

  • Use Swagger annotations to document REST endpoints

  • Use a context specific documentation format such as the documentation attribute of the @Batchjob annotation