Code Style¶

This page documents the code style rules followed across Flowing Code's open source projects.

Canonical source

Content on this page is derived from the Flowing Code DevelopmentConventions repository (style guide version 1.0.5), licensed under Apache 2.0.

In any file format, maintain a consistent style for indentation and alignment throughout the entire file. Do not mix tab characters and spaces on different lines, as their display can differ across devices and platforms.

Java¶

Apply the Google Java Style Guide.

Formatter¶

Configure your editor with the Google Java formatter:

Eclipse — download the eclipse-java-google-style formatter. Remove the preset sorting order of import statements.
IntelliJ — install the google-java-format plugin. See its README for further configuration.
VS Code — use Google's Eclipse formatter as explained in the VS Code Java linting docs.
Maven — run mvn com.spotify.fmt:fmt-maven-plugin:format.

Local variable type inference (`var`)¶

For local variables declared with var (Java 10+), follow the Local Variable Type Inference Style Guidelines:

Diamond operator¶

Prefer diamond constructor invocation (Java 7+) for fields and for variables without inferred types:

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

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

Early returns¶

Use early returns as guard clauses for handling preconditions. They improve readability by simplifying control flow, reducing nesting, and making error conditions explicit.

public void foo(String myString) {
    if (myString == null) {
        return;
    }
    // Main logic continues here
}

JavaDoc¶

Use the Google Java Style Guide, Section 7 as the primary reference. For topics not covered there or here, defer to Oracle's How to Write Doc Comments for the Javadoc Tool.

Punctuation in `@param` and `@return`¶

Start the description with an uppercase letter only if the first phrase is a complete sentence.
End the description with a period only if it is a complete sentence or contains multiple sentences or phrases.

Examples:

@param x  the x-coordinate, measured in pixels
@param x  the x-coordinate. Measured in pixels.
@param x  Specifies the x-coordinate, measured in pixels.
@param x  Specifies the x-coordinate. Measured in pixels.

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> when needed). Each JavaDoc comment is treated as a unique scope for this rule.

The following identifiers must never be linked and must 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).

The restriction applies only to the type identifier itself. {@link} must still be used for the first reference to specific methods or fields belonging to those restricted types.

/**
 * Wraps a {@code Bar} into a new {@code Foo} container.
 * <p>The internal name is derived via {@link Bar#getName()}.
 * If {@code Bar#getName()} returns {@code null}, then the internal name is randomized.
 *
 * @param bar the {@code Bar} instance to be wrapped
 */
public Foo(Bar bar) { ... }

Deprecation¶

To deprecate an API, use both the @Deprecated annotation and the @deprecated JavaDoc tag.

The annotation lets tooling identify deprecated APIs; the tag documents the reason and the recommended alternative.

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