Java Coding Standards

This page documents the standard adopted for Java code in the Qpid project. All committers are expected to follow these standards; checkstyle or similar is used to check compliance.

Executive Summary

The main things in the standard are:

• Indent using four spaces. No tabs.
• braces always go on new lines, e.g.

if (x == 5)
{
    System.out.println("Hello");
}

rather than

if (x == 5} {
    System.out.println("Hello");
}

• Always add braces, e.g.

  if (x == 5)
  {
      System.out.println("Hello");
  }
  

rather than

if (x == 5}
    System.out.println("Hello");

• Fields prefixed with underscores, e.g. _messageCount
• Spaces after keywords but no spaces either before or after parentheses in method calls, e.g.

  if (x == 5)
  

  rather than

  if(x==5)
  

  but

  foo.bar(4, 5)
  

  rather than

  foo.bar( 4, 5 )
  

Details

Introduction

This document describes two types of coding standard:

1. Mandatory standards must be followed at all times.
2. Recommended standards should in general be followed but in particular cases may be omitted where the programmer feels that there is a good reason to do so.

Code that does not adhere to mandatory standards will not pass the automated checks (or a code review if the guideline is not stylistic).

Source files

This section defines the general rules associated with the contents of a Java source file and the order in which the each part should be presented. No rules on programming style, naming conventions or indentation are given here.

1. Java source files must have a ".java" suffix (this will be enforced by the compiler) [mandatory].

2. The basename of a Java source file must be the same as the public class defined therein (this will be enforced by the compiler) [mandatory].

3. Only one class should be defined per source file (except for inner classes and one-shot uses where the non-public class cannot conceivably be used outside of its context) [mandatory].

4. Source files should not exceed 1500 lines [recommended].

5. No line in a source file should exceed 120 characters [mandatory].

6. The sections of a source file should be presented in the following order [mandatory]:

• File information comment (see rule 7 below).
• Package name (see rules 1 to 3 in the section 2.1 above and rule 8 below).
• Imports (see rules 9 to 10 below).
• Other class definitions.
• Public class definition.

1. Do not use automatically expanded log or revision number provided by your source code management system unless it provides a facility to avoid "false conflicts" when doing merges due simply to revision number changes (which happens, for example, with cvs when branches are used). [mandatory]

2. Every class that is to be released must be a member of a package [mandatory].
   Rationale: classes that are not explicitly put in a package are placed in the unnamed package by the compiler. Therefore as the classes from many developers will be being placed in the same package the likelihood of a name clash is greatly increased.

3. All class imports from the same package should be grouped together. A single blank line should separate imports from different packages [recommended].

4. Use javadoc tags and use HTML mark-up to enhance the readability of the output files [mandatory].