code-style.md

Flowing Code Style Guide / 1.0.3-rc1

In any file format, avoid using tab characters to replace a fixed amount of whitespace in any file format, as their display can differ across devices and platforms.

Java

Apply the Google Java Style Guide

Formatter

• Eclipse: download the eclipse-java-google-style formatter. Remove the preset sorting order of import statements as shown below.
• IntelliJ: install the google-java-format plugin. For further configuration and installations instructions refer to this documentation.
• VSCode: use Google's Eclipse formatter as explained here.
• Maven: execute mvn com.spotify.fmt:fmt-maven-plugin:format

Local Variable Type Inference

Regarding the use of var (introduced in Java 10), follow the Local Variable Type Inference Style Guidelines

• Choose variable names that provide useful information.
• Minimize the scope of local variables.
• Consider var when the initializer provides sufficient information to the reader.
• Use var to break up chained or nested expressions with local variables.
• Take care when using var with diamond or generic methods.
• Take care when using var with literals.

Prefer diamond constructor invocation (introduced in Java 7) for fields and for variables without inferred types. For instance:

Map<String,List<Integer>> map = new HashMap<>();

Instead of:

Map<String,List<Integer>> map = new HashMap<String,List<Integer>>();

JavaDoc

Apply the Google Java Style Guide (Section 7)

When to use {@code}

Prefer {@code} over <code>, unless the code contains a closing brace (}).

In each comment, the first occurrence of an identifier that refers to a class, field, or method must be enclosed in a {@link} tag. Otherwise, the identifier must be wrapped in {@code} (or <code> see #39).

The following identifiers must never be linked and should always be wrapped in {@code}:

• The name of the type being documented, or the type where the documented method/field is located.
• The names of the field type, method return type, and argument types.
• Exceptions listed in the throws` clause of the documented method.
• The names of the direct supertype and any implemented interfaces of the documented type (in a type-level comment).

  /**
   * Creates a new instance of {@code FooBar}.
   */
  public FooBar() { ... }

Deprecation

To indicate deprecation use both the @Deprecated annotation and the @deprecated JavaDoc tag.

The @Deprecated annotation allows tools to identify deprecated APIs, while the @deprecated tag provides documentation that explains the reasons for deprecation and suggests alternatives.

  /** Sets the foo.
   * @param foo the foo to be set.
   * @deprecated Use {@code setFooBar} instead.*/
  @Deprecated(forRemoval = true)
  void setFoo(Object foo) {
    // ...
  }