Java Coding Conventions

© 2005, Martin Rinehart
from www.MartinRinehart.com

Introduction

Why So Many Other Conventions?

In alphabetical order, the non-Sun conventions are:

• Scott W. Ambler, coauthor of The Elements of Java Style, publishes his own conventions at Ambler.
• The Infospheres team at CalTech (editors Joseph Kiniry and Daniel M. Zimmerman) posts its conventions at Caltech.
• Geotechnical Software Services, a Norwegian software company has an excellent, recent convention set available at Geosoft.
• New England Java User Group's active conventions committee (Doug Chamberlin, editor) has published a short book at NEJUG.

References to Conventions

Ambler numbers sections (6 Classes, Interfaces, ... — 6.1 Classes — 6.1.1 Class Visibility). A reference to class visibility in Ambler is [Ambler 6.1.1].

Caltech does not provide a comparable navigation feature but it does provide a convenient, hyper-linked table of contents at the top. The reference to a naming convention will be [Caltech Naming Conventions].

Geosoft's organization is similar to Sun and Ambler (6 Layout and Comments — 6.1 Layout) but it numbers each convention consecutively. The first convention under 6.1 is "58 Basic indentation ...". This will be referred to as [Geosoft 58].

The New England Java User Group proposes Standards (must be followed — STD), Styles (should be followed, but some room for decision — STY) and Conventions (no recommendation, but make up your own mind and stick to your decision — CON). Style 13, Ternary Statement Usage, will be referred to as [NEJUG STY-13].

I have tried to be complete. For example, 2.2 Package Comments includes references to Ambler and to Caltech. This implies that the other three conventions do not address this issue.

Comment Types

Organization

1. General
2. Package
3. Compilation Unit
4. Type (Class and Interface)
5. Class-Wide Data
6. Methods
7. Statements Within Methods

This paper doesn't cover "good advice" conventions that programmers using any language should know (choose meaningful variable names, for example). This paper also excludes requirements (the compiler reads files with a ".java" suffix). It focuses on choices the programmer needs to make. This document is not a substitute for the referenced documents — they include many useful examples and discussions of the options. The goal here is a terse summary that lets you see where the standards agree, disagree and are silent.

Contents 1 General   1.1 Conventions About Conventions   1.2 Language   1.3 Implementation Comments   1.4 Acronyms   1.5 Other 2 Package 3 Compilation Unit 4 Type (Class and Interface) 5 Class-Wide Data 6 Methods 7 Statements Within Methods Conventions Map

1 General

  1.1 Conventions About Conventions

Ambler's Law ([Ambler 1.5]) states that conventions are preferred in order of increasing generality. Industry conventions are better than organization conventions; organization conventions are better than project conventions, which in turn are better than personal conventions, which are better than no conventions.

  1.2 Language

  1.3 Implementation Comments

  1.4 Acronyms

  1.5 Other

[Caltech Structure] recommends that javadoc comments end with **/. The other standards do not specifically address this but all their examples show javadoc ending with */.

No convention specifies that javadoc comments have empty top and bottom lines, but all examples are done this way:

    /**
     * doc comment here
     */

Contents 1 General 2 Package   2.1 Package Names   2.2 Package Comments 3 Compilation Unit 4 Type (Class and Interface) 5 Class-Wide Data 6 Methods 7 Statements Within Methods Conventions Map

2 Package

  2.1 Package Names

  2.2 Package Comments

Contents 1 General 2 Package 3 Compilation Unit   3.1 Compilation Unit Names   3.2 Compilation Unit Comments   3.3 Compilation Unit Format     3.3.1 Compilation Unit Sections     3.3.2 Package and Import Statements     3.3.3 Line Length and Breaks     3.3.4 Indentation   3.4 Compilation Unit Other 4 Type (Class and Interface) 5 Class-Wide Data 6 Methods 7 Statements Within Methods Conventions Map

3 Compilation Unit

  3.1 Compilation Unit Names

  3.2 Compilation Unit Comments

[Sun 3] also suggests an optional comment identifying the sections of the file.

Embedded HTML tags in comments are specified by [Caltech Documentation] in an effort to make intra-file navigation as simple as Javadoc navigation. (Caltech does not claim to have solved the problem, only to be working on a solution.)

  3.3 Compilation Unit Format

    3.3.1 Compilation Unit Sections

The order within a file is beginning comments, package and import statements, then class and interface declarations, per [Sun 3.1.1] and [NEJUG STY-1]. The public type comes before any others.

    3.3.2 Package and Import Statements

The imports should use "*" (as in java.awt.*) according to [Ambler 7.2], and shouldn't use "*", according to [Ambler 7.2.1] and [Caltech Structure]. [NEJUG STY-3] considers both positions and concludes that "*" should be used for standard (Sun) classes but not for your own classes. The order of imports is java.xxx first, javax.xxx next and then others alphabetically according to [Caltech Structure] and [Geosoft 36]. [NEJUG STY-2] suggests that third-party packages be imported between Sun's and your own. [Sun 3.1.2] only says that imports follow the package statement.

    3.3.3 Line Length and Breaks

Over-length lines must be broken. The broken part is indented ([Sun 4.1], [Ambler 2.4.3], [Geosoft 34] and [NEJUG STY-8]). Breaks are after commas and operators (except Sun, which specifies breaking before binary operators). Geosoft and NEJUG strongly disagree, stating that the "broken" condition of the line should be made as obvious as possible — which means the break is after the operator.

    3.3.4 Indentation

• 4 spaces, with tabs set every 8 spaces [Sun 4]
• Using a tab is the only sensible decision [Ambler 2.4.2 footnote 2]
• 2 spaces and tab characters are not allowed [Caltech Structure]
• 2 spaces and neither tabs nor page breaks are allowed [Geosoft 33, 58]
• 2, 3, 4 or 8 spaces (pick one and stick to it) and tabs are not allowed [NEJUG STY-9, 10].

  3.4 Compilation Unit Other

Contents 1 General 2 Package 3 Compilation Unit 4 Type (Class and Interface)   4.1 Type Names   4.2 Type Comments   4.3 Type Format     4.3.1 Format of the Type Statement     4.3.2 Items Within the Type     4.3.3 Order of Methods   4.4 Type Other 5 Class-Wide Data 6 Methods 7 Statements Within Methods Conventions Map

4 Type (Class and Interface)

  4.1 Type Names

[Caltech Naming Conventions] also suggests starting with "Abstract" and ending with "Factory" and "Exception" for the respective class types, and ending with "Impl" for an implementation. [Geosoft 27, 28] specifies starting with "Default" and ending with "Exception" for those types.

[Ambler 1.3] recommends against names longer than 15 characters.

  4.2 Type Comments

An implementation comment should follow the type statement, per [Sun 5.2].

// end of class Xxx may follow the closing brace, per [Caltech Structure].

  4.3 Type Format

    4.3.1 Format of the Type Statement

type name extends superclassname
  implements interface list

    4.3.2 Items Within the Type

1. javadoc comment
2. class or interface statement
3. type implementation block comment if necessary
4. static variables (public, then protected, then package, then private)
5. instance variables (same order)
6. constructors
7. other methods

No convention mentions the main() method. This is a problem for me as I almost always write a main() for testing and comment it out after testing is completed. Once commented out, it is invisible to my IDE so I cannot navigate to it — or I couldn't if I didn't know that it immediately precedes the first constructor.

    4.3.3 Order of Methods

• Grouped by functionality, not scope or access — [Sun 3.1.3]
• Methods alphabetically after constructors (unless functional grouping is documented) — [NEJUG STY-5]
• Constructors, finalize(), then in inverse visibility — public, protected, package, private (data and methods combined); statics may precede non-statics within each group — [Ambler 6.1.4.2]
• Constructors, finalizers, initializers, statics, publics with private helpers, Static initializers go between static and instance fields. Keep statics together, instance together and offset them by comments [Caltech Structure].

• By a single blank line [Sun 6.4], [Sun 8.1]
• By two blank lines [NEJUG STY-28], [Caltech Structure]
• By 3 to 5 blank lines [Geosoft 73]

  4.4 Type Other

Contents 1 General 2 Package 3 Compilation Unit 4 Type (Class and Interface) 5 Class-Wide Data   5.1 Class-Wide Data Names   5.2 Class-Wide Data Comments   5.3 Class-Wide Data Format   5.4 Class-Wide Data Other 6 Methods 7 Statements Within Methods Conventions Map

5 Class-Wide Data

  5.1 Class-Wide Data Names

Avoid long names (over 15 chars) and names differing only in case [Ambler 1.3].

Name widgets with a postfix type: okButton, nameField ([Ambler 3.1.2] and [Geosoft 18]).

Collections: use plural noun: customers, products ([Ambler 3.1.4] and [Geosoft 19]).

Private class variables should have an underscore suffix (name_) [Geosoft 8]. Generic variables should have the same name as their type (Database database) [Geosoft 9]. Use an "n" prefix for number of (nLines) [Geosoft 20]. Use a "No" suffix for entity number (employeeNo) [Geosoft 21]. Use complement names (first/last, next/previous) [Geosoft 23]. Don't abbreviate (ActionEvent event) [Geosoft 24]. Associated constants should share a prefix (COLOR_RED, COLOR_BLUE) [Geosoft 26].

  5.2 Class-Wide Data Comments

Collections of a single type should have an EOL comment (ArrayList coins; // of Coin) [Geosoft 80].

  5.3 Class-Wide Data Format

Offset groups with comments [Caltech Structure].

Left-align variable names in declarations ([Sun 6.1], [Geosoft 74]). Example:

    Widget[]    widgets;
    int         nWidgets;

  5.4 Class-Wide Data Other

Initialize fields in declarations or in a constructor, but not both ([NEJUG STY-17]). Define constants in an interface ([NEJUG CON-13]).

Contents 1 General 2 Package 3 Compilation Unit 4 Type (Class and Interface) 5 Class-Wide Data 6 Methods   6.1 Method Names   6.2 Method Comments   6.3 Method Format   6.4 Method Other 7 Statements Within Methods Conventions Map

6 Methods

  6.1 Method Names

Converter methods start with "to" (toDegrees()) [Caltech Naming Conventions].

Geosoft has much more to say about method names. The name of the object should not be included (line.getLength(), not line.getLineLength()) [Geosoft 12]. If the method computes something, use "compute" (computeAverage() ) [Geosoft 15]. Use "find" for lookup (findNearestVertex() ) [Geosoft 16]. Use "initialize" (printer.initializeFontSet() ) [Geosoft 17]. Use complement names (get/set, add/remove) [Geosoft 23]. Don't abbreviate (computeAverage()) [Geosoft 24]. Don't negate booleans (isFound(), not isNotFound() ) [Geosoft 25]. Methods returning data should be named after what they return; void methods after what they do [Geosoft 29].

  6.2 Method Comments

Implementation comments should precede methods [Sun 5.1]. Implementation comments should explain what and why [NEJUG CON-11]. Implementation comments cover control structure, what/why, local variables, difficult or complex code, and processing order. [Ambler 2.3.3].

For non-trivial methods, document the closing brace [Ambler 2.3.3]:

public type whateverMethod(parameters) {
...
... non-trivial code here
...
} // end of whateverMethod()

  6.3 Method Format

[Geosoft 38] Specifies the order for the modifiers to be access, static, abstract, synchronized, , final, native.

It is agreed that no space separates the name and open parenthesis [Sun 6.4], [NEJUG STD-3].

The parameters are all on one line, or each can be on its own line, per [Caltech Structure].

There is no agreement on the location of the open brace. It goes on the same line as the name [Sun 6.4] or on the next line [Caltech Structure], [Geosoft 59].

Both styles place the close brace on a line by itself, indented to the start of the name line — [Sun 6.4], [Caltech Structure].

[Sun 6.4] specifies "{}" for an empty method.

[Geosoft 61] specifies this method format:

public void someMethod()
  throws SomeException
{
...
}

  6.4 Method Other

Use minimal visibility [Ambler 2.2]. Getters/setters should be protected, if possible [Ambler 3.4.3].

Constructors should leave objects in a stable state [NEJUG CON-2]. Methods should accomplish a single task [NEJUG CON-3].

In a group of size recommendations, NEJUG stresses that the exact number should be set to meet the organization's needs. Limit methods to 30 (or other) lines [NEJUG CON-4]. Limit number of methods to 30 (or other) [NEJUG CON-6]. Limit number of parameters to 5 (or other) [NEJUG CON-9]. Minimize public methods and variables [NEJUG CON-7].

Contents 1 General 2 Package 3 Compilation Unit 4 Type (Class and Interface) 5 Class-Wide Data 6 Methods 7 Statements Within Methods   7.1 Variable Names   7.2 Statement Comments   7.3 Statement Formats     7.3.1 Agreed Statement Conventions     7.3.2 Formatting the Ternary Expression     7.3.3 Declarations Formats     7.3.4 Block Statement Formats     7.3.5 Switch Formats     7.3.6 Try/Catch/Finally Formats     7.3.7 Miscellaneous Formatting   7.4 Statement Other Conventions Map

7 Statements Within Methods

  7.1 Variable Names

Single-letter names are OK for "throwaway" variables (very limited scope) such as loop counters [Sun 9.5], [Ambler 4.1.2], [Geosoft 11]. Just "e" is OK for an Exception [Ambler 4.1.3] and "i", "j", "k" can name iterators (Iterator i = ...) [Geosoft 22].

[Ambler 4.1.1] suggests xxxStream for streams and later, [Ambler 5.1] suggests using the same name conventions for parameters as for other variables.

[Geosoft 24] warns us not to abbreviate (ActionEvent event).

  7.2 Statement Comments

• Leading comment blocks are preferred over numerous (code obscuring) comments [NEJUG STY-20]
• A blank line should precede an implementation block comment (including a single-line block comment) [Sun 8.1], [NEJUG STY-19, 28]
• Single-line block comments should be indented to match following code [Sun 5.1.2], [NEJUG STY-19]

• [Sun 5.1.3] uses block comments for trailing, single-line notes
• EOL comments also used for trailing comments and to comment out code blocks, but not for comment blocks [Sun 5.1.4].
• EOL comments are used to comment out code blocks [NEJUG STY-18].
• EOL comments are used for comment blocks, block comments are used to comment out code blocks [Ambler 1.4.1], [Caltech Documentation], [Geosoft 78].

  7.3 Statement Formats

    7.3.1 Agreed Statement Conventions

Blank lines should be used to "paragraph" — group related lines together — the code ([Sun 8.1], [Ambler 2.4.2, 2.4.4], [Geosoft 72], [NEJUG STY-28]). Similarly, a blank line can separate variable declarations from the start of the code ([Sun 8.1] and [NEJUG STY-28]).

The standards are nearly unanimous in stressing the use of parentheses as superior to depending on precedence rules ([Sun 10.5.1], [Ambler 2.4.7], [Caltech Structure], [NEJUG CON-16]).

We should use a single space:

• between any keyword and an open parenthesis ([Sun 8.2], [Caltech Structure]and [NEJUG CON-14]
• after the commas in a parameter list ([Sun 8.2], [NEJUG CON-14])
• after the semicolons in a "for" loop control expression ([Sun 8.2])
• on either side of a binary operator, but not between a unary operator and its operand ([Sun 8.2], [Caltech Structure], [NEJUG CON-14])
• after a cast ([Sun 8.2]

    7.3.2 Formatting the Ternary Expression

    1 a = (expr) ? b : c;
    2 a = (expr) ? b
                 : c;
    3 a = (expr)
          ? b
          : c;

[Sun 10.5.3] specifies that the ternary's condition is always parenthesized.

    7.3.3 Declarations Formats

[Geosoft 47] tells us to initialize loop variables just before the loop:

    boolean isDone=false;
    while (!isDone)
    {
    ...
    }

[Sun 6.2] and [Geosoft 40] specify initialization of local variables where declared (if possible). [NEJUG STY-16] agrees but only if the initial values are not the default values as this adds to the code size and is redundant. Sun's example declarations show ints being initialized to zero.

    7.3.4 Block Statement Formats

    if (expr) {
        statement[s];
    }

    if (expr)
    {
        statement[s];
    }

    if (expr) {
        statement[s]
    } else {
        statement[s]
    }

We should always use braces [Sun 7.2], [Caltech Structure], [NEJUG STY-24] or we can skip them for a single-line statement [Geosoft 69]. If you use the single-line statement, it should be on a separate line, per [Geosoft 52].

    if (expr)
        statement;

If necessary to break a conditional, indent the broken part(s) 8 spaces and the following block statement just 4 spaces ([Sun 4.2]).

An empty block after a "for" statement should be a semi-colon on the same line as the "for" [Sun 7.5] or it should be a semi-colon placed on the following line [Geosoft 63, 64]. This also applies to "while" loops ([Sun 7.5]).

    7.3.5 Switch Formats

    switch (condition) {
        case A:
            statements;
            break;
        case B:
            statements;
            break;
        default:
            statements;
            break;
    }

Additionally [Geosoft 70] specifies a single space before the colon (case A :).

    7.3.6 Try/Catch/Finally Formats

    try {
        statements;
    } catch (ExceptionClass e) {
        statements;
    } finally {
        statements;
    }

    7.3.7 Miscellaneous Formatting

[Geosoft 44] declares arrays with brackets next to type(int[] foo, not int foo[]).

[Geosoft 75] asks for horizontal alignment to be used to enhance readability:

   aWidget.      addMouseListener();
   theWidget.    addMouseListener();
   anotherWidget.addMouseListener();

Contents 1 General 2 Package 3 Compilation Unit 4 Type (Class and Interface) 5 Class-Wide Data 6 Methods 7 Statements Within Methods Conventions Map

  7.4 Statement Other

Return boolean (or ternary) rather than use multiple returns within an if/else construct ([Sun 10.5.2]).

Document local variables with an EOL comment ([Ambler 4.2]). Also, never reuse local variables ([Ambler 4.2] and [Geosoft 41]).

Additional conventions from Geosoft are:

• Always cast (float f = (float) i) [Geosoft 39]
• Avoid do/while loops [Geosoft 48]
• Avoid break and continue [Geosoft 49]
• Use temporary booleans to simplify complex conditionals [Geosoft 50]
• Normal case in "if" part, exception in "else" part [Geosoft 51]
• Use a decimal point and at least one decimal for floats [Geosoft 55]
• Use at least one digit to the left of the decimal point for floats [Geosoft 56]

Appendix - Convention Coverage Map

Back to Articles