Versions Compared

Old Version 15

changes.mady.by.user Raúl Kripalani

Saved on

compared with

New Version 16

changes.mady.by.user Anton Vinogradov

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Note
titleOverview of TODOs
  • Ordering: Order of class members is not defined.
  • Javadoc: Define when it's possible to use \{@inheritDoc\}.
  • Javadoc: Incongruence in one-liner Javadocs (see TODOs below).
  • Javadoc: Define indentation policy with multi-line parameter descriptions.
  • Imports: Define the order of class imports on a package basis (java, javax, org.apache.ignite, org.apache, etc.).Imports: Review the requirement that Javadoc references to classes not imported by source code must be Review the requirement that Javadoc references to classes not imported by source code must be resolved by an import rather than by citing the FQN in Javadoc. This does not play well with OSGi and messes up any dependency analysis efforts.Imports: Define a policy for static member imports.
  • Whitespacing: Improve empty lines policy in several situations (see relevant TODO).

General Points

Avoid redundant initialization/assignment

...

Code Block
java
java
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):

Code Block
titleBad
/**
 * {@inheritDoc}
 */
public void m() { ... }
Code Block
titleGood
/** {@inheritDoc} */
public void m() { ... }

Naming

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

...

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

Code Block
java
java
/**
 * Type description.
 *
 * @author John Doe
 */
/

Every method, 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:

Code Block
java
java
/**
 * 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) {
}
Code Block
javajava
/** Array index. One-line comment is only allowed for fields. */
private int index;
Code Block
java
java
/**
 * Some meaningful comment. 
 */
static {
}

...

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

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

Code Block
titleBad
/**
 * {@inheritDoc}
 */
@Owerride public void m() { ... }
Code Block
titleGood
/** {@inheritDoc} */
@Override public void m() { ... }

One-line Javadoc comments allowed and preferred for fields.

Code Block
java
java
/** Array index. One-line comment is only allowed for fields. */
private int index;
Note
titleTODO
  • Define indentation policy with multi-line parameter descriptions.

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:

Code Block
java
java
a += b; b = a; a * (c + b) / d

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

Code Block
java
java
!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 separeted by a new line.

Code Block
languagejava
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;
Note
titleTODO
  • When is \{@inheritDoc\} allowed.
  • The "One-line comment is only allowed for fields." rule in this section is incoherent with the rules set out in Shorter one-line Javadoc above. The examples are contradictory.
  • Define indentation policy with multi-line parameter descriptions.

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

Use imports instead of FQNs in Javadoc links.

 

Note
titleTODO
  • Define the order of imports based on packages.
    • Define a policy for static member imports.
    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 comments (/ /' or //) that span more then 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
    Source code line should not be longer then 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).
    ...
    • between them.
    Whitespaces and empty lines
    Source code line should not be longer then 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).
    Empty lines should be used according to following rules:
    WhereNumber of empty lines required
    Before package statement0
    Before imports1
    Between imports and static imports1
    Before class header1
    After class header0
    Between class definition and EOF1
    Between class members (filelds, methods, initializers)1
    Between minimal semantic units in the method or initializer body1
    . 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 method name and opening (.
    For exampleExample:
     Code Block
    java
    java
    /**
 * 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");
            System.out.println("One more Woo-hoo");
               
            return;
        }
    }
}

     Note
    titleTODO
    Strictly define empty lines policy in these situations, at least:
    Image Removed
    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 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.
    ...