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.
Table of Contents |
---|
Executive Summary
The main things for layout purposes in the standard are:
- Indent using four spaces. No tabs.
- braces always go on new lines, e.g.
Code Block |
---|
if (x == 5)
{
System.out.println("Hello");
}
|
rather than
Code Block |
---|
if (x == 5} {
System.out.println("Hello");
}
|
Always add braces, e.g.
Code Block if (x == 5) { System.out.println("Hello"); }
rather than
Code Block |
---|
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.
Code Block if (x == 5)
rather than
Code Block if(x==5)
but
Code Block foo.bar(4, 5)
rather than
Code Block foo.bar( 4, 5 )
Details
Introduction
...
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.
...
- Java source files must have a ".java" suffix (this will be enforced by the compiler) \ [mandatory\].
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\].Wiki Markup 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\].Wiki Markup Source files should not exceed 1500 lines \ [recommended\].Wiki Markup No line in a source file should exceed 120 characters \ [mandatory\].unmigrated-wiki-markupWiki Markup - 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.
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\]unmigrated-wiki-markupWiki Markup - 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. All class imports from the same package should be grouped together. A single blank line should separate imports from different packages \ [recommended\].Wiki Markup Use javadoc tags and use HTML mark-up to enhance the readability of the output files \ [mandatory\].Wiki Markup
Java Elements
This section gives advice on coding the various elements of the Java programming language.
...
This section gives guidelines for class and interface definitions in Java. The term class in this section is used more broadly to mean class and interface:
Class names should start with a capital letter with every subsequent word capitalised, for example: DataProcessor \ [mandatory\].Wiki Markup Wiki Markup The name of exception classes should end in the word exception, for example: UnknownMungeException \[mandatory\].
- All classes should be preceded by a javadoc comment describing the purpose of the class [recommended].
- Class-level javadoc comments should specify the thread-safety of the class [recommended].
- The name of exception classes should end in the word exception, for example: UnknownMungeException [mandatory].
- Class names should in general not be overloaded. For example, defining a class
Class names should in general not be overloaded. For example, defining a class "com.foo.bar.String" should be avoided as there is already a class "java.lang.String" \ [recommended\].Wiki Markup
Rationale: adhering to this rule reduces the likelihood of confusion and means that the use of fully qualified class names should not be required. The definition of the primary class (i.e. the class with the same name as the java file) should start in column 0 of the source file. Inner class definitions should be indented 4 spaces more than their enclosing class \ [mandatory\].unmigrated-wiki-markupWiki Markup - Declare a class as final only if specialisation will never be required and improved performance is essential. With modern JVMs there in fact may be no performance advantage. Warning: use of final limits code reuse \ [mandatory\].
Wiki Markup For
all
but
simplest
classes
the
following
methods
should
have
useful
definitions
\[recommended
\]:
Code Block public boolean equals(Object obj) public int hashCode() public String toString()
Wiki Markup - The order of presentation of the sections in a class should be \ [mandatory\]:
- Variables
- Methods
Variables
This section gives guidelines for class and instance variable definitions in Java. In this section if a rule uses the term variable rather than instance variable or class variable, then the rule applies to both types of variable.
...
- The order of presentation of variables in a class definition should be \ [recommended\]:
- private, protected, public: static final variables (aka constant class variables).
- private, protected, public: static variables (aka class variables).
- private, protected, public: final variables (aka constant instance variables).
- private, protected, public: variables (aka instance variables).
It should be noted that as javadoc will automatically order variables in a consistent manner, rigid adherence to this rule is not necessary.
Variable modifiers should be presented in the following order: static, final, transient, volatile \ [mandatory\].Wiki Markup Wiki Markup The
names
of
static
final
variables
should
be
upper
case
with
subsequent
words
prefixed
with
an
underscore
\[mandatory
\].
For
example:
Code Block public static final int NOT_FOUND = -1;
Wiki Markup - When a subclass refers to a static final variable defined in a parent class, access should be qualified by specifying the defining class name \ [mandatory\]. For example: use ParentClass.MAX rather than MAX.
Wiki Markup The
names
of
variables
(other
that
static
final)
should
start
with
a
lower
case
letter.
Any
words
that
are
contained
in
the
rest
of
the
variable
name
should
be
capitalised
\[mandatory
\].
For
example:
Code Block String name; String[] childrensNames;
Wiki Markup - Class and instance variables must be prefixed with an underscore (_) \ [mandatory\].
Wiki Markup Variables
must
not
be
named
using
the
so-called
Hungarian
notation
\[mandatory
\].
For
example:
Code Block int nCount = 4; // not allowed
Wiki Markup - Only one variable may be defined per line \ [mandatory\].
Variable declarations should be indented 4 spaces more than their enclosing class \ [mandatory\].unmigrated-wiki-markupWiki Markup - All variables should be preceded by a javadoc comment that specifies what the variable is for, where it is used and so forth. The comment should be of the following form and be indented to the same level as the variable it refers to \ [mandatory\recommended]
Never declare instance variables as public unless the class is effectively a "struct" \ [mandatory\].unmigrated-wiki-markupWiki Markup - Never give a variable the same name as a variable in a superclass \ [mandatory\].
Ensure that all non-private class variables have sensible values even if no instances have been created (use static initialisers if necessary, i.e. "static \ { ... \ }") \ [mandatory\].Wiki Markup
Rationale: prevents other objects accessing fields with undefined/unexpected values.Methods
This section gives guidelines for class and instance method definitions in Java. In this section if a rule uses the term method rather than instance method or class method, then the rule applies to both types of method. Constructors and finalize methods should follow immediately after the variable declarations \ [mandatory\].Wiki Markup Do not call non-final methods from constructors. This can lead to unexpected results when the class is subclassed. If you must call non-final methods from constructors, document this in the constructor's javadoc \ [mandatory\]. Note that private implies final.Wiki Markup Methods that are associated with the same area of functionality should be physically close to one another \ [recommended\].Wiki Markup - After grouping by functionality, methods should be presented in the following order [recommended]:
- private, protected, public: static methods.
- private, protected, public: instance methods.
It should be noted that as javadoc will automatically order methods in a consistent manner, rigid adherence to this rule is not necessary.
...
- Method modifiers should be presented in the following order: abstract, static, final., synchronized \ [mandatory\]unmigrated-wiki-markup
- When a synchronized method is overloaded, it should be explicitly synchronized in the subclass \ [recommended\].unmigrated-wiki-markup
Method
names
should
start
with
a
lower
case
letter
with
all
subsequent
words
being
capitalised
\[mandatory
\].
For
example:
Code Block protected int resize(int newSize) protected void addContentsTo(Container destinationContainer)
Wiki Markup Methods
which
get
and
set
values
should
be
named
as
follows
\[mandatory
\]:
Code Block Type getVariableName() void setVariableName(Type newValue)
Exceptions should be used to report any failure to get or set a value. The "@param" description should detail any assumptions made by the implementation, for example: "Specifying a null value will cause an error to be reported".
unmigrated-wiki-markup- Method definitions should be indented 4 spaces more than their enclosing class \ [mandatory\].
AllWiki Markup - methods should be preceded by a javadoc comment specifying what the method is for, detailing all arguments, returns and possible exceptions. This comment should be of the following form and be indented to the same level as the method it refers to \[mandatory\]:All non-private methods should be preceded by a javadoc comment specifying what the method is for, detailing all arguments, returns and possible exceptions [mandatory]
The braces associated with a method should be on a line on their own and be indented to the same level as the method [mandatory]. For example:
Code Block public void munge() { int i; // method definition omitted... }
Wiki Markup - The body of a method should be indented 4 columns further that the opening and closing braces associated with it \ [mandatory\]. See the above rule for an example.
When declaring and calling methods there should be no white space before or after the parenthesis \ [mandatory\].unmigrated-wiki-markup].Wiki Markup In
argument
lists
there
should
be
no
white
space
before
a
comma,
and
only
a
single
space
(or
newline)
after
it
\[mandatory
\].
For
example:
Code Block public void munge(int depth, String name) { if (depth > 0) { munge(depth - 1, name); } // do something }
Wiki Markup - Wherever reasonable define a default constructor (i.e. one that takes no arguments) so that Class.newInstance() may be used \ [recommended\]. If an instance which was created by default construction could be used until further initialisation has been performed, then all unserviceable requests should cause a runtime exception to be thrown.
The method public static void main() should not be used for test purposes. Instead a test/demo program should be supplied separately. \ [mandatory\].unmigrated-wiki-markupWiki Markup - Public access methods (i.e. methods that get and set attributes) should only be supplied when required \ [mandatory\].unmigrated-wiki-markup
- If an instance method has no natural return value, declare it as void rather than using the "return this;" convention \ [mandatory\].unmigrated-wiki-markup
- Ensure that non-private static methods behave sensibly if no instances of the defining class have been created \ [mandatory\].
Expressions
This section defines the rules to be used for Java expressions: Unary operators should not be separated from their operand by white space \ [mandatory\].unmigrated-wiki-markupWiki Markup - Embedded ++ or -- – operators should only be used when it improves code clarity \ [recommended\]. This is rare.unmigrated-wiki-markup
- Extra parenthesis should be used in expressions to improve their clarity \ [recommended\].
The logical expression operand of the "?:" (ternary) operator must be enclosed in parenthesis. If the other operands are also expressions then they should also be enclosed in parenthesis [mandatory]. For example:
Code Block biggest = (a > b) ? a : b; complex = (a + b > 100) ? (100 * c) : (10 * d);
Wiki Markup - Nested "?:" (ternary) operators can be confusing and should be avoided \ [mandatory\].
Use of the binary "," operator (the comma operator) should be avoided \ [mandatory\]. Putting all the work of a for loop on a single line is not a sign of great wisdom and talent.unmigrated-wiki-markupWiki Markup If
an
expression
is
too
long
for
a
line
(i.e.
extends
beyond
column
119)
then
it
should
be
split
after
the
lowest
precedence
operator
near
the
break
\[mandatory
\].
For
example:
Code Block if ((state == NEED_TO_REPLY) || (state == REPLY_ACK_TIMEOUT)) { // (re)send the reply and enter state WAITING_FOR_REPLY_ACK }
Furthermore if an expression requires to be split more than once, then the split should occur at the same logical level if possible.
unmigrated-wiki-markup- All binary and ternary operators (exception for ".") should be separated from their operands by a space \ [mandatory\].
Statements
Simple Statements
This section defines the general rules for simple Java statements:
There must only be one statement per line \ [mandatory\].Wiki Markup In general local variables should be named in a similar manner to instance variables \ [recommended\].Wiki Markup Wiki Markup More
than
one
temporary
variable
may
be
declared
on
a
single
line
provided
no
initialisers
are
used
\[mandatory
\].
For
example:
Code Block unmigrated-wiki-markupint j, k = 10, l; // Incorrect! int j, l; // Correct int k = 10;
- A null body for a while, for, if, etc. should be documented so that it is clearly intentional \ [mandatory\].
Wiki Markup Keywords
that
are
followed
by
a
parenthesised
expression
(such
as
while,
if,
etc)
should
be
separated
from
the
open
bracket
by
a
single
space
\[mandatory
\].
For
example:
Code Block unmigrated-wiki-markupif (a > b) { munge(); }
In
method
calls,
there
should
be
no
spaces
before
or
after
the
parentheses
\[mandatory
\].
For
example:
Code Block munge (a, 10); // Incorrect! munge(a, 10); // Correct.
Compound Statements
This section defines the general rules associated with compound statements in Java:
The body of a compound statement should be indented by 4 spaces more than the enclosing braces \ [mandatory\]. See the following rule for an example.Wiki Markup Wiki Markup The
braces
associated
with
a
compound
statement
should
be
on
their
own
line
and
be
indented
to
the
same
level
as
the
surrounding
code
\[mandatory
\].
For
example:
Code Block unmigrated-wiki-markupif ((length >= LEN_BOX) && (width >= WID_BOX)) { int i; // Statements omitted... }
If
the
opening
and
closing
braces
associated
with
a
compound
statement
are
further
than
20
lines
apart
then
the
closing
brace
should
annotated
as
follows
\[mandatory
\]:
Code Block for (int j = 0; j < SIZE; j++) { lotsOfCode(); } // end for
Wiki Markup All
statements
associated
with
an
if
or
if-else
statement
should
be
made
compound
by
the
use
of
braces
\[mandatory
\].
For
example:
Code Block if (a > b) { statement(); } else { statement1(); statement2(); }
Wiki Markup The
case
labels
in
a
switch
statement
should
be
on
their
own
line
and
indented
by
a
further
4
spaces.
The
statements
associated
with
the
label
should
be
indented
by
4
columns
more
than
the
label
and
not
be
enclosed
in
a
compound
statement.
\[mandatory
\].
For
example:
Code Block switch (tState) { case NOT_RUNNING: start(); break; case RUNNING: default: monitor(); break; }
Wiki Markup - In switch statements - the statements associated with all cases should terminate with a statement which explicitly determines the flow of control, for example break \ [recommended\].
In switch statements - fall through should be avoided wherever possible, however if it is unavoidable it must be commented with "// FALLTHROUGH" \ [mandatory\].Wiki Markup Wiki Markup - In switch statements - a default case must be present and should always be the last case \ [mandatory\].
General
This section gives general rules to be followed when programming in Java:unmigrated-wiki-markup - When comparing objects for equivalence use the method equals() and not the == operator. The only exceptions to this are static final objects that are being used as constants and interned Strings \ [mandatory\].
In general labelled break and continue statements should be avoided \ [recommended\]. This is due to the complex flow of control, especially when used with try/finally blocks.unmigrated-wiki-markupWiki Markup Unless
some
aspect
of
an
algorithm
relies
on
it,
then
loops
count
forward
\[mandatory
\].
For
example:
Code Block for (int j = 0; j < size; j++) { // Do something interesting }
Wiki Markup Use
local
variables
in
loops
\[recommended
\].
For
example:
Code Block ArrayList clone = (ArrayList)listeners.clone(); final int size = clone.size(); for (int j = 0; j < size; j++) { System.out.println(clone.elementAt(j)); }
Wiki Markup - Anonymous inner classes should define no instance variables and be limited to three single line methods. Inner classes that declare instance variables or have more complex methods should be named \ [mandatory\].unmigrated-wiki-markup
Use
final
local
variables
where
possible
to
help
avoid
errors
in
code
\[recommended
\].
For
example:
Code Block public void foo() { final int x = dataSource.getCount(); // do things with x // ... } ... }
- To indicate that further work is intended on a section of code, add a comment prefixed by "TODO" explaining what needs to be done and why [recommended].
- If code is so incomplete that executing it would lead to incorrect or confusing results, throw UnsupportedOperationException with an explanatory message [mandatory].
Exceptions
This section gives general guidance on the use of exceptions when programming in Java.
Wiki Markup try/catch
blocks
should
be
laid
out
like
any
other
compound
statement
\[mandatory
\].
For
example:
Code Block try { String str = someStrings[specifiedIndex]; } catch (IndexOutOfBoundsException ex) { // The user specified an incorrect index, better take // some remedial action. }
4. When an exception is caught but ignored then a comment should be supplied explaining the rationale (note that this rule includes InterruptedException, which should almost never be ignored) [mandatory]. For example:
Code Block try { propertySet.setProperty("thingy", new Integer(10)); } catch (UnknownPropertyException ignore) { // This exception will never occur as "thingy" definitely exists }
Wiki Markup All
exceptions
that
are
likely
to
be
thrown
by
a
method
should
be
documented,
except
if
they
are
runtime
exceptions
(note:
the
compiler
will
not
enforce
catch
blocks
for
runtimes
even
if
they
are
mentioned
in
the
throws
clause)
\[mandatory
\].
For
example:
Code Block /* Comment snippet: * @exception IllegalValueException Thrown if values is null or * any of the integers it contains is null. */ private Integer sum(Integer[] values) throws IllegalValueException
IDE Code Style
There is a code style file for the IntelliJ IDE located at /etc/IntelliJ_Qpid_Style.xml in the source tree. All Qpid Java developers should use this or an equivalent style for their IDE.