Page History

...

Java coding guidelines are largely based on SUN official Java coding conventions: http://java.sun.com/docs/codeconv/html/CodeConventions.doc.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 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 maintenanceand thorough as well as simplify maintenance.

General Points

Avoid redundant initialization/assignment

...

/** {@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):

...

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();
 while (true) {
   else if (falsetrue) {
        bodyfoo();
      else if bar(true) {;
    }
    else
 {
       }abc();
}

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;

else
    a = b - c;

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

...

/**
 * Type description.
 *
 * @author John Doe
 */

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:

/**
 * DecsriptionDescription.
 * 
 * @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 meaningfullmeaningful comment. 
 */
static {
}

NOTE: multiline comments in Javadoc tags should be idented indented 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.

...

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).

...

Use imports instead of FQNs in Javadoc links.

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:

...

/**
 * 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 {
        if (i > 0) { // Do recursion.
            try {
                for (int j = 0; j < 10; j++)
                    method(i--);
            }
            catch (MyException e) {
                e.printStackTrace();
            }
        }

        switch (i) {
            case 10: 
                return i - 1;

            case 11:
                i += 2;
                i /= 10;

                break;

            default:
                assert false;
        }

        // No javadoc for anonymous classes.
        MyInterface itf = new MyInterface() {
            @Override public int myMethod(int p) {
                return p++;
            }
        };

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

Line Breaking

If source code line gets 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 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.

...

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

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

...

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

...

Assertions and parameter validation

...

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

Commented out code

...