Page History

Introduction

This document describes formatting rules and guidelines for software source code. Note that this document does not cover best programming practices or techniques. It is solely concentrating on source code formatting and conventions.

Java coding guidelines are largely based on SUN official Java coding conventions: httphttps://javawww.sunoracle.com/docstechnetwork/codeconv/html/CodeConventions.docJava/codeconvtoc-136057.html. Below are the only exceptions, clarifications, and additions to this standard that are specific to Apache Ignite development process.

RationaleRational
Studies have shown that 80% of development time is spent on software maintenance, which involves software source code understanding, refactoring, and support. Established and enforced code formatting rules and guidelines improve source code readability, promote team code ownership, allow engineers understand new code more quickly and thorough as well as simplify maintenance.

General Points

Avoid redundant initialization/assignment

General Points

Avoid redundant initialization/assignment

String s = null;

s = "GridGain";

String s = "GridGainnull;

s = "Apache Ignite";

String s = "Apache Ignite";

Use of "!" instead of explicit "== true" and "== false"

Use a shortened form of boolean expression where it does not compromise the readability.

Anonymous inner classes.

Use a shorter form of "callbacks" are allowed now where it does not compromise the readability:

collection.add(new A() {
    @Override public void m() {
        // Do something.
    }
});

Shorter one-line Javadoc

Use a shorter version of Javadoc (mostly for Javadoc Tag only):

/**
 * {@inheritDoc}
 */
public void m() { ... }

/** {@inheritDoc} */
public void m() { ... }

Naming

Except for types (classes, interfaces, enumerations and annotations) and semantic constants names all other names should start with low-case letter. Types names should start with an upper-case letter. In the both cases a camel style should be used. Symbol '_' (underscore) should be used only to separate upper-case letters in the names. Constants (final class attributes that have constant semantic and not just made final because of inner class access or performance considerations) should all be upper-case. For example (class comments ommitted):

...

class Window implements ScreenObject {
    /** */
    private int currIndex;

    /** */
    private int serialUid;

    /** */
    private static final int MAX_INDEX = 10;

    /**
     * @param uid UID.
     * @return Class name.
     */
    public String classNameByUid(Long uid) {
        . . .
    }
}

Abbreviations

Types and methods names are NOT abbreviated except for well-known cases such as EOF, Fifo, etc. See Abbreviation Rules for list of currently accepted abbreviations.

Braces and Identation

K&R bracing and indentation style should be used. { starts on the same line as the opening block statement. For example:

...

while (true) {
    if (false) 
        body();
    else if (true) {
    }
    else {
    }
}

Members sort order

Same as described at Oracle's Java Code Conventions.

Naming

Except for types (classes, interfaces, enumerations and annotations) and semantic constants names, all other names should start with a low-case letter. Types names should start with an upper-case letter. In both cases, a camel style should be used. Symbol '_' (underscore) should be used only to separate upper-case letters in the names. Constants (final class attributes that have constant semantic and are not just made final because of inner class access or performance considerations) should all be upper-case. For example (class comments omitted):

class Window implements ScreenObject {
    /** */
    private static final int MAX_INDEX = 10;

    /** */
    private int currIndex;

    /** */
    private int serialUid;

    /**
     * @param uid UID.
     * @return Class name.
     */
    public String classNameByUid(Long uid) {
        . . .
    }
}

Abbreviations

Types and methods names are NOT abbreviated except for well-known cases such as EOF, Fifo, etc. See Abbreviation Rules for a list of currently accepted abbreviations.

Braces and Indentation

K&R bracing and indentation style should be used. { starts on the same line as the opening block statement. For example:

while (true) {
    if (false) 
        body();
    else if (true) {
        foo();
        bar();
    }
    else
        abc();
}

Braces are required in all cases, even if not required by syntax, except for the cases when the next statement is a one-liner. For the latter, braces must not be used, e.g.:

if (someCondition)
    a = b + c;
else
    a = b - c;

4-space characters should be used for both tabulation and indentation.

When a multi-line operator (try-catch, anonymous class instantiation, etc) goes after some condition it is required to use braces:

if (someCondition) {
    try {
        invocation();
    }
    catch (Exception e) {
        e.printStackTrace();
    }
}

Javadoc Comments

All javadoc comments should be approximately 80 characters long. Always keep in mind that we create Javadoc for people to read - it should be easy to consume and easy to understand.

• When you need to insert Java code snippet:
  1. Put into <blockquote class="snippet"></blockquote>
  2. Use http://www.java2html.de/applet.html to convert Java into colored HTML
     1. Target XHTML 1.0 Transitional (inlined fonts)
     2. Style: Kawa
     3. Tab-space: 4
     4. Alignment: left
     5. Line numbers: ON
     6. Table border: OFF
  3. Copy <font...> tags into <blockquote> (make sure to remove <code> from both ends)
• When you need to insert any non-Java code snippet:
  1. Put into <pre class="snippet"></pre>
• When creating table:
  1. Use <table class="doctable">
  2. Use <th> for header columns.
  3. No other styles on <th>, <tr> or <td>.
• To mark important text used <strong> HTML element.
• For paragraph titles user <h1 class="header">.

Every type should start with at least minimal Javadoc comments including a description in the following form:

/**
 * Type description.
 */

Every method, field or initializer public, private or protected in top-level, inner or anonymous type should have at least minimal Javadoc comments including description and description of parameters using @param, @return and @throws Javadoc tags, where applicable. For example:

/**
 * Description.
 * 
 * @param i Integer parameter.
 * @param f Float parameter. Long comment, foo
 *      bar, foo bar, foo bar.
 * @return Double value.
 */
public double foo(int i, float f) {
}

/**
 * Some meaningful comment. 
 */
static {
}

NOTE: multiline comments in Javadoc tags should be indented by 4 or 5 characters depending on the configuration of IDE. In most IDEs the single TAB click will produce only 1 character indentation which is not enough for readability. The second click on TAB will shift it to (1+4) 5 characters. This is the only exception from 4-characters tabulation rule.

It is ok to have empty (/* /) or auto-generated Javadoc comments for code elements that are "work in progress". However, it is not allowed to not have a Javadoc comment at all, i.e. every field, method, initializer or type regardless of visibility scope should have at least empty Javadoc with minimally required Javadoc tags (see above).

The description must be separated by one blank line from Javadoc tags.

/ / or // comments should be avoided in between methods, fields or types. Such comments in most cases should be used within the methods.

All comments should follow English grammar and punctuation including starting with an upper-case letter and ending with '.'. No technical jargon is allowed in the comments.

All identifiers in the Javadoc comments must be placed within <tt></tt> or linked to, if possible, using {@link ClassName} or {@link ClassName#method} constructs.

Shorter one-line Javadoc

Method's javadoc should be equals to /** {@inheritDoc} */ in case it overrides or implements method without changing contracts declared at parent's javadoc.

Use a shorter version of  {@inheritDoc}.

/**
 * {@inheritDoc}
 */
@Owerride public void m() { ... }

/** {@inheritDoc} */
@Override public void m() { ... }

One-line Javadoc comments allowed and preferred for fields.

/** Array index. One-line comment is only allowed for fields. */
private int index;

Method Parameters

Two styles of method parameter declaration are allowed. The first style is preferred when all parameters can fit in a single line before the page delimiter (120 char limit).

public void foo(Object obj1, Object obj2, Object obj3, ..., Object objN)

If parameters can't fit on a single line, parameters are split by 120 char limit to several lines. 

The second style requires a new line for every parameter.

public void foo(
    Object obj1,
    Object obj2, 
    ... ,
    Object objN
)

Mixing declaration styles is not allowed.

Spacing

Source code has special spacing rules (mostly inherited from Sun's Java source code guidelines and mentioned here for better clarity).

In comma-separated enumerations, there is always a space between the comma and the next element in the list. For example, foo(p1, p2, p3) Notice spaces between comma ',' and the next parameter.

There is always a space between operands and the binary operation itself. For example:

a += b; b = a; a * (c + b) / d

There should be no space between unary operation and its operand. For example:

!a, ~b, -b, b++

Notice also that all assignments by this rule should have space around '=' symbol: int a = b

Comments should be separated by space from "// ", "/ , "/** "* or " */". For example, / Notice the space. /

Package Importing

• < >

Use per-class importing.

In case of the naming conflict - use fully qualified names (FQN).

Use imports instead of FQNs in Javadoc links.

Import should be ordered alphabetically, but packages starting with 'java.' should be declared prior to others. 

Static imports should follow same rules as regular imports and be separated by a new line.

import java.util.ArrayList;
import java.util.Collection;
import org.apache.ignite.lang.IgniteUuid;
import org.apache.ignite.thread.IgniteThread;
import org.jsr166.ConcurrentHashMap8;

import static java.util.concurrent.TimeUnit.MILLISECONDS;
import static org.apache.ignite.events.EventType.EVT_NODE_FAILED;
import static org.apache.ignite.events.EventType.EVT_NODE_JOINED;
import static org.apache.ignite.events.EventType.EVT_NODE_LEFT;

Braces are required in all cases, even if not required by syntax, except for the cases when next statement is one-liner. For the latter, braces must not be used, e.g.:

if (someCondition)
    a = b + c;

4-space characters should be used for both tabulation and indentation.

When multi-line operator (try-catch, anonymous class instantiation, etc) goes after some condition it is required to use braces:

if (someCondition) {
    try {
        invocation();
    }
    catch (Exception e) {
        e.printStackTrace();
    }
}

Javadoc Comments

All javadoc commetns should be approximately 80 characters long. Always keep in mind that we create Javadoc for people to read - it should be easy to consume and easy to understand.

• When you need to insert Java code snippet:
  1. Put into <blockquote class="snippet"></blockquote>
  2. Use http://www.java2html.de/applet.html to convert Java into colored HTML
     1. Target XHTML 1.0 Transitional (inlined fonts)
     2. Style: Kawa
     3. Tab-space: 4
     4. Alignment: left
     5. Line numbers: ON
     6. Table border: OFF
  3. Copy <font...> tags into <blockquote> (make sure to remove <code> from both ends)
• When you need to insert any non-Java code snippet:
  1. Put into <pre class="snippet"></pre>
• When creating table:
  1. Use <table class="doctable">
  2. Use <th> for header columns.
  3. No other styles on <th>, <tr> or <td>.
• To mark important text used <strong> HTML element.
• For paragraph titles user <h1 class="header">.

Every type should start with at least minimal Javadoc comments including description and author information in the following form:

...

/**
 * Type description.
 */

Every method, field or initializer public, private or protected in top-level, inner or anonymous type should have at least minimal Javadoc comments including description and description of parameters using @param, @return and @throws Javadoc tags, where applicable. For example:

...

/**
 * Decsription.
 * 
 * @param i Integer parameter.
 * @param f Float parameter. Long comment, foo
 *      bar, foo bar, foo bar.
 * @return Double value.
 */
public double foo(int i, float f) {
}

...

/** Array index. One-line comment is only allowed for fields. */
private int index;

...

/**
 * Some meaningfull comment. 
 */
static {
}

NOTE: multiline comments in Javadoc tags should be idented by 4 or 5 characters depending on configuration of IDE. In most IDEs the single TAB click will produce only 1 character identation which is not enough for readability. Second click on TAB will shift it to (1+4) 5 characters. This is the only exception from 4-characters tabulation rule.

It is ok to have empty (/* /) or auto-generated Javadoc comments for code elements that are "work in progress". However, it is not allowed to not have a Javadoc comment at all, i.e. every field, method, initializer or type regardless of visibility scope should have at least empty Javadoc with minimally required Javadoc tags (see above).

Description must be separated by one blank line from Javadoc tags.

/ / or // comments should be avoided in between methods, fields or types. Such comments in most cases should be used within the methods.

All comments should follow English grammar and punctuation including starting with upper-case letter and ending with '.'. No technical jargon is allowed in the comments.

All identifiers in the Javadoc comments must be placed within <tt></tt> or linked to, if possible, using {@link ClassName} or {@link ClassName#method} constructs.

Note also that only fields allow one-line Javadoc comments.

Spacing

Source code has special spacing rules (mostly inherited from Sun's Java source code guidelines and mentioned here for better clarity).

In comma-separated enumerations there is always a space between comma and the next element in the list. For example, foo(p1, p2, p3) Notice spaces between comma ',' and the next parameter.

There is always a space in between operands and binary operation itself. For example:

...

a += b; b = a; a * (c + b) / d

There should be no space between unary operation and its operand. For example:

...

!a, ~b, -b, b++

Notice also that all assignments by this rule should have space around '=' symbol: int a = b

Comments should be separated by space from "// ", "/ , "/** "* or " */". For example, / Notice the space. /

Package Importing

Use per-class importing.

In case of the naming conflict - use fully qualified names (FQN).

...

Semantic Units

The source code should be broken into minimal semantic units and all such units must be separated by one empty line. To simplify the recognition of semantic units, the every line of the source code should be separated by one empty line except for the following cases:

• Between lines in continues continuous comments (/ /' or //) that span more then than one line.
• Between import statements.
• After { and } brackets.
• Between Javadocs tags in the comment.
• Between code comment and corresponding code line.
• Between Javadocs comment /* / and corresponding element (type, method, initializer, or variable).
• Between one-line case statements in switch operator.
• Between identical (similar) language constructs, i.e. identical (similar) method calls or operations, e.g. multiple setter or getter calls can be grouped together without empty lines between them.

Whitespaces and empty lines

Source code line should not be longer then than 120 characters (to be visible on most conventional monitors). 4 space characters should be used for tabulation and indentation. IDE should be configured to replace tabulation with spaces (to properly see source code on the platforms with different tabulation sizes).Single empty line should be used to separate types, methods and initializers in the type. Single empty line should also be used for separation of semantical (to properly see source code on the platforms with different tabulation sizes).

Empty lines should be used according to the following rules:

. Note that single blank line SHOULD NOT be used for the mere decoration of the source code. Avoid using double empty lines.

Blanks space (1 space character) should be used before opening ( or {. { and } should always be the last tokens in the line (except for the possible comments). However, blank space should not be used between the method name and opening (.

For exampleExample:

/**
 * Class definition example.
 *
 * @author @java.author
 * @version @java.version
 */
class Foo {
    /**
 * Class definition example.
 *
 * @author @java.author
 * @version @java.version
 */
class Foo {
    /**
     * Example method.
     *
     * @param i Example parameter.
     * @throws MyException Thrown in case of any error.
     */
    public void method(int i) throws MyException {
**
     * Example method.
     *
     * @param i Example parameter.
     * @throws MyException Thrown in case of any error.
     */
    public void method(int i) throws MyException {
        if (i > 0) { // Do recursion.
            try {
                for (int j = 0; j < 10; j++)
                   if method(i--);
 > 0) { // Do recursion.
      }
      try {
     catch (MyException e) {
        for (int j = 0; j < 10; j++) e.printStackTrace();
            }
        method(i--);}

        switch (i) {
  }
          case 10: catch
 (MyException e) {
             return i - e.printStackTrace()1;

            case }11:
        }

        switch (i) {i += 2;
            case 10: 
  i /= 10;

            return  i - 1break;

            case 11default:
                i += 2assert false;
        }

        // No javadoc ifor /= 10;

anonymous classes.
        MyInterface itf = new MyInterface() {
     break;

       @Override public int myMethod(int p) default:{
                assertreturn falsep++;
        }

    }
    // No javadoc for anonymous classes. };

        MyInterfaceif itf(i = new MyInterface(< 0) {
 // Exit now.
         @Override public int myMethod(int p) {System.out.println("Woo-hoo");
            System.out.println("One more Woo-hoo");
  return p++;
            }
        }    return;

        }
 if (i < 0) { // Exit now.
            System.out.println("Woo-hoo");
               
            return;
        }
    }
}

Line Breaking

If source code line gets longer than 120 characters it should be broken. The rule is to start consequent line 4 spaces to the right relatively to first line. All other lines 3rds, 4th, etc. (if overall line gets longer than 120x2) should start on the same indentation as 2nd line. No other decorative rules are allowed.

In other words, the current line should never be indented more then 4 spaces to the right from the previous line.

The line should be broken on the last '.' or ',' character that fits into 120 character margin.

String Output

 }
}

Line Breaking

If source code lines and/or Javadoc lines get longer than 120 characters it should be broken. The rule is to start consequent line 4 spaces to the right relative to the first line. All other lines 3rds, 4th, etc. (if the overall line gets longer than 120x2) should start on the same indentation as 2nd line. No other decorative rules are allowed.

In other words, the current line should never be indented more than 4 spaces to the right from the previous line.

The line should be broken on the last '.' or ',' character that fits into 120 character margin.

String Output

All output debug/logging output including toString() methods and exception messages should follow the next BNF:

output:	prefix
	| prefix ": " postfix
	| prefix '[' nv-pairs ']'
	;
nv-pairs: pair
	| pair ", " pair
	;
pair:  name '=' value
	;
prefix, postfix, name, value: java.lang.String
	;

For example:

throw new CacheException("Invalid type [type=" + type + ", xid=" + tx.getXid() + ']');
throw new WorkflowException("Invalid rule: " + rule.getName());

Note that all prefixes, postfixes, names and values should follow English grammar, in particular, start with upper case and end with the dot '.'.

If it is necessary to output error message (e.g. from exception) as name-value pair it should have err name. For exampleAll output debug/logging output including toString() methods and exception messages should follow the next BNF:

output:	prefix
	| prefix ": " postfix
	| prefix '[' nv-pairs ']'
	;
nv-pairs: pair
	| pairthrow new GridException("Failed to instantiate bean [type=" + GridConfiguration.class + ", err=" pair
	;
pair:  name '=' value
	;
prefix, postfix, name, value: java.lang.String
	;

For example:

...

throw new CacheException("Invalid type [type=" + type + ", xid=" + tx.getXid() + ']');
throw new WorkflowException("Invalid rule: " + rule.getName());

+ e.getMessage() + ']', e);

Do not use error, errMsg, etc.

Java 5

Java 5 added many additional useful features that significantly improve the quality of code.

• @Override
  • When overriding methods from the parent class always use @Override annotation.
• Generics
  • Always use generics when types of classes are known in advance.
• Use foreach loops whenever possible.
  • for (String s : list) { ...

Java 8

Java 8 added lambda expressions and Stream API.

While lambda expressions are more expressive and concise, good old anonymous classes are still preferred in Apache Ignite code base.

Stream API is convenient means of data processing but usage of this API should be avoided in most cases because it can lead to unpredictable and uncontrolled creation of class instances and therefore create additional pressure on GC.

@Annotations

All annotations must be placed on a separate line, except for @Nullable and @Override, as in the following

Note that all prefix, postfix, name, value should follow English grammar, in particular, start with upper case and end with the dot '.'.

If it is necessary to output error message (e.g. from exception) as name-value pair it should have err name. For example:

throw new GridException("Failed to instantiate bean [type=" + GridConfiguration.class + ", err=" + e.getMessage() + ']', e);

Do not use error, errMsg, etc.

JDK 1.5

Java5 added many additional useful features that significantly improve quality of code.

• @override
  • When overriding methods from parent class always use @override annotation.
• Generics
  • Allways use generics when types of classes are known in advance.
• Use foreach loops whenever possible.
  • for (String s : list) { ...

@Annotations

...

/** {@inheritDoc} */
@SuppressWarning("foobar")
@Nullable @Override public String toString() {
    return "something";
}

@Nullable and @Override annotations should be in the same sequence as shown in the example.

We do not use @NotNull annotation.

Warning suppression

Don't use statement warning suppression.

public static <T> T[] newArray(Class<T> type, int length) {
    //noinspection unchecked
    return (T[])Array.newInstance(type, length);
}

@SuppressWarnings({"unchecked"})
public static <T> T[] newArray(Class<T> type, int length/** {@inheritDoc} */
@SuppressWarning("foobar")
@Nullable @Override public String toString() {
    return "something" (T[])Array.newInstance(type, length);
}

@Nullable and @Override annotations should be in the same sequence as shown in the example.

We do not use @NotNull annotation.

Warning suppression

Assertions and parameter validation

When the correctness of code depends on some preconditions or expectations (including values of the call arguments) they should be expressed explicitly using assert statements. In public API methods, functions from GridArgumentCheck class should be used for argument check instead of assertDon't use statement warning suppression.

Capsule(State statepublic static <T> T[] newArray(Class<T> type, int length) {
    //noinspection uncheckedassert state != null;

    return (T[])Array.newInstance(type, length)this.state = state;
}

@SuppressWarnings({"unchecked"})
public static <T> T[] newArray(Class<T> type, int length) {
    return (T[])Array.newInstance(type, length);
}

Assertions and parameter validation

When correctness of code depends on some preconditions or expectations (including values of the call arguments) they should be expressed explicitly using assert statements. In public API methods functions from GridArgumentCheck class should be used for argument check instead of assert.

...

Capsule(State state) {
    assert state != null;

    this.state = state;
}

...

public SomePublicConstructor(int max) {
    A.ensure(max > 0, "max > 0");

    this.max = max;
}

public SomePublicConstructor(int max) {
    A.ensure(max > 0, "max > 0");

    this.max = max;
}

toString(), equals(), hashCode()

If a class overrides toString() method, this method goes last.

If a class overrides equals() and hashCode() methods, they should go before toString(), if it is present, or last.

Getters and setters

Getters and setters should be implemented without is/get/set prefixes in internal APIs.

TODOs

Use next format for TODOs.

// TODO: IGNITE-xxx, <description of what should be done>.

It's mandatory to use a related JIRA ticket number. 

Commented out code

We try not to use commented-out code. If there is no another option and code have to be commented then TODOs (with related JIRA ticket) have to be added before commented out code.

Appendices:

A. Configure IntelliJ IDEA code style

In order to configure IntelliJ IDEA for Ignite code style follow these steps:

• copy ignite\idea\ignite_codeStyle.xml to <user_home>\.IdeaIC14\config\codestyles (or to ~/Library/Preferences/IntelliJIdea14/codestyles on Mac)
• select ignite in IDE Settings -> Code Style

Configure IDEA to stripe trailing spaces and add a blank line to the end of the file.

Image Added

B. Broken tests

We try to not use commented code. So, in case if test(s) is broken the test should be annotated @Ignore with a related to JIRA ticket comment which describes reason of failure.

If the test hangs or works too long then 

@Ignore("https://issues.apache.org/jira/browse/IGNITE-10178")

The annotation should be added in the line preceding respective @Test annotation.

To disable all tests in *Test class use the same annotation at the line preceding class declaration.

@Ignore("https://issues.apache.org/jira/browse/IGNITE-10178")
public class SomeTest() {
    //...
}

Additionally, it is recommended to use Assume API (org.junit.Assume) if you want to conditionally skip some tests.

Assume.assumeFalse

toString(), equals(), hashCode()

If a class overrides toString() method, this method goes last.

If a class overrides equals() and hashCode() methods, they should go before toString(), if it is present, or last.

Getters and setters

Getters and setters should be implemented without get/set prefixes in internal APIs.

TODOs

Use next format for TODOs.

// TODO: IGNITE-xxx, <description of what should be done>.

It's mandatory to use related JIRA tiket number. 

Commented out code

We try not using commented out code. If there is no another option and code have to be commented then TODOs (with related JIRA ticket) have to be added before commented out code.

Appendices:

A. Configure IntelliJ IDEA code style

In order to configure IntelliJ IDEA for Ignite code style follow these steps:

• copy incubator-ignite\idea\ignite_codeStyle.xml to <user_home>\.IdeaIC14\config\codestyles (or to ~/Library/Preferences/IntelliJIdea14/codestyles on Mac)
• select ignite in IDE Settings -> Code Style

Configure IDEA to stripe trailing spaces and add blank line to the end of file.

Image Removed

B. Broken tests

We try to not use commented code. So, in case if test(s) is broken the test should be muted on TeamCity with a related to JIRA ticket comment which describe a reason of fail.

If test hangs or works too long then 

fail("https://issues.apache.org/jira/browse/IGNITE-111310178");

method should be added as first line of the test.

To disable all tests in *Test class use 

...

, conditionToSkip());

C. Code Inspection

Apache Ignite has settings of inspection rules that are recommended to use during Ignite development. Settings can be found at <project directory>\.idea\inspectionProfiles\Project_Default.xml and will be automatically set as project default settings at first checkout.

You can enable this profile manually using the following steps for IntelliJ IDEA:
File → Settings → Editor → Code Style → Inspections → Configure inspections (gearwheel) → Import Profile... → Select a file and import

D. Abbreviation Plugin

It is recommended to install IntelliJ IDEA plugin for abbreviation advice Abbreviation Rules IntelliJ Idea Plugin.