Skip to content

Latest commit

 

History

History
101 lines (76 loc) · 5.05 KB

code-style.md

File metadata and controls

101 lines (76 loc) · 5.05 KB

Flowing Code Style Guide / 1.0.4

In any file format, maintain a consistent style for indentation and alignment throughout the entire file. Do not use tab characters on some lines and a fixed amount of whitespace on others, 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

image

Local Variable Type Inference

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

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>>();

Early returns

Using early returns as guard clauses for handling preconditions is preferred because it enhances code readability by simplifying structure and flow, reducing cognitive load for readers, and allowing the main logic to proceed cleanly with more explicit error conditions. This approach also minimizes indentation and nesting, making the logic easier to follow, particularly in larger functions.

Example:

public void foo(String myString) {
   if (myString == null) {
      return;
   } 
   // Do something more here...
}

JavaDoc

Use the Google Java Style Guide (Section 7) as the primary reference. For topics not addressed there or in this document, defer to Oracle's How to Write Doc Comments for the Javadoc Tool.

Punctuation and capitalization rules for @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> 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) {
    // ...
  }