Page History

...

Java source files have the following ordering:

• Beginning comments
• Package and import statements
• Class and interface declarations

Beginning comments

All source files must begin with the comments shown in the following code sample.

...

When an expression will not fit on a single line, break it according to these general principles:

• break after a comma;
• break before an operator;
• prefer higher level breaks to lower level breaks;
• align the new line with the beginning of the expression after the assignment;
• if the above rules lead to confusing code or to code that's squished up against the right margin, please use common sense.

Some examples breaking an arithmetic expression. The first is preferred, since the break occurs outside the parenthesised expression:

...

When coding Java classes and interfaces, the following formatting rules should be followed:

• no space between a method and its parameter list
• "{" is on a line by itself indented to match its corresponding opening statetment, except when it is a null statement, in which case the "{" should appear on the same line as the opening statement
• "}" starts a line by itself indented to match its corresponding opening statement, except when it is a null statement, in which the case the "}" should appear immediately after the "{".

Example:

class ShipmoTrial extends Trial
{
    int m_index = 0;

    ShipmoTrial(int index)
    {
        m_index = index;
    }

    void emptyMethod() {}
}

...

Compound statements are statements that contain lists of statements enclosed in braces ("{...}"):

• The enclosed statements should be indented one more level than the compound statement.
• The opening brace should be at the end of the line that begins the compound statement; the closing brace should begin a line and be indented to the beginning of the compound statement.
• Braces are used around all statements, even single statements, when they are part of a control structure, such as a if-else or for statement. This makes it easier to add statements without accidentally introducing bugs due to forgetting to add braces.

if, if-else, if else-if else statements

...

When using a switch statement use following guidelines:

• Every switch statement should include a default case. The break in the default case is redundant, but it prevents a fall-through error if later another case is added.
• The so-called fall-through construction should be avoided. Only when there are good reasons to use it, make sure that it is very clear that a fall-through is used (comment it).

The next example shows the sample code that uses the guidelines for a switch statement:

...

Two blank lines should always be used in the following circumstances:

• between class and interface definitions;
• between a group of methods that belong together (by its functionality or because they are part of the same interface).

One blank line should always be used in the following circumstances:

• between methods;
• before a block or single line comment;
• between logical sections inside a method to improve readability.

Blank spaces

Blank spaces should be used in the following circumstances:

• A keyword followed by a parenthesis should be separated by a space.

  Code Block
  while (ready == false) { ... }

  Note that blanks should not be used between a method call and its opening parenthesis. This helps to distinguish keywords from function calls.
• Blanks should appear after commas in argument lists.
• All binary operators except "." should be separated from their operands by spaces. Blanks should never separate unary operators such as unary minus, increment("++") and decrement("--") from their operands.

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

• The expressions in a for statement should be separated by blanks.

  Code Block
  for (expr1; cond1; expr2)

• Casts should be followed by a blank.

  Code Block
  myInstance.doIt((TreeFrame) frame);

Naming conventions

Naming conventions make programs more understandable by making them easier to read. They can also give information about the function of the identifier.

...

Note: All Java identifiers are case sensitive.

References

• Java Code Conventions - Sun Microsystems, Inc.
  No ref. number, only hyperlink: http://java.sun.com/docs/codeconv/

...

• How to Write Doc Comments for JavaDoc - Sun Microsystems, Inc.
  http://java.sun.com/products/jdk/javadoc/writingdoccomments.html

...

• JavaDoc homepage - Sun Microsystems, Inc.
  http://java.sun.com/products/jdk/javadoc/

...

• Eclipse formatting template.