The jCoderZ.org Project Java Coding Guidelines

Code conventions are important to programmers for a number of reasons:

For the conventions to work, every person at jCoderZ.org writing software must conform to the code conventions.

This document is the result of the merger of 2 sources:

The document is maintained by the jCoderZ.org Project. Comments can be sent the web site at http://www.jcoderz.org/.

This document contains a list of rules ordered by different aspects. In general all given rules must be respected in order to make the code more readable.

If conforming to these rules leads to code that is harder to read and understand, you might break these rules and choose another style for small parts of your code. You must prefer open standards when using another convention and document the convention and the reason for breaking these rules.

The inability to conform to this guideline might be a strong indication that the given code approach could be enhanced. To avoid major rework tasks, please get in contact with any member of the jCoderZ.org Project in order to get assistance for the given coding problem.

If you are faced with a problem that is not covered by any of the rules in this document, get in contact with the jCoderZ.org Project or use the referred document to identify a solution.

The Book Writing Robust Java Code [Ambler00] is a reading recommendation and gives a good introduction for novice and advanced software engineers.

Conformance to this coding guideline will automatically be checked by Checkstyle. If non-conforming code is detected, the code author will be contacted and asked to enhance his source code.

All source files must begin with the following header:

/*
 * $Id: SampleSnippets.java 1011 2008-06-16 17:57:36Z amandel $
 *
 * Copyright 2006, The jCoderZ.org Project. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met:
 *
 *    * Redistributions of source code must retain the above copyright
 *      notice, this list of conditions and the following disclaimer.
 *    * Redistributions in binary form must reproduce the above
 *      copyright notice, this list of conditions and the following
 *      disclaimer in the documentation and/or other materials
 *      provided with the distribution.
 *    * Neither the name of the jCoderZ.org Project nor the names of
 *      its contributors may be used to endorse or promote products
 *      derived from this software without specific prior written
 *      permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS" AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS
 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
 * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

You don't have to bother with filling in Id into this header as they are automatically filled via CVS/SVN functionality.

The package declaration must follow immediately after the file header.

For import statements the “single-type import statements” must always be used:

import java.io.IOException;
import java.io.Serializable;

Using single-type imports is quite useful and makes it easy for the reader to determine the package of a particular type. Do not use “On-demand import statements”:

import java.util.*; // DON'T

Import statements should be lexicographically sorted and grouped according to the upper level packages (Recommendation).

The following table describes the parts of a class or interface declaration, in the order that they should appear:

Implementation comments are those which are delimited by /*...*/ and //. They are means for commenting out code or for adding information about the particular implementation. Doc comments are meant to describe the specification of the code, from an implementation-independent perspective. It is meant for developers who might not necessarily have the source code at hand.

Comments should be used to give an overview of the code and provide additional information that are not readily available in the code itself. Comments should contain only information that are relevant to reading and understanding the program. For example, information about how to build the corresponding package or in what directory it resides should not be stated as a comment.

Discussions of non-trivial or non-obvious design decisions are appropriate, but avoid duplicating information that is present and clearly visible in the code. Redundant comments get outdated too easily. In general, avoid any comments that are likely to get outdated as the code evolves.

Note: A high frequency of comments sometimes reflects poor quality of code. When you feel compelled to add a comment, consider rewriting the code to make it clearer. Comments must not be enclosed in large boxes drawn with asterisks or other characters.

Doc comments describe Java classes, interfaces, constructors, methods, and fields. Each doc comment is set inside the comment delimiters /**...*/.

/**
 * The Example class provides ...
 * @author Stephen Mohr
 * @author Oliver Griffin
 */
public class ExampleClass
{
    // ...
}

The first line of doc comments (/**) for classes and interfaces is not indented. Subsequent doc comment lines each have 1 space of indentation (to vertically align the asterisks). Members, including constructors, have three spaces for the first doc comment line and four spaces thereafter. Doc comments should not be positioned inside a method or constructor definition block, because Java associates documentation comments with the first declaration after the comment.

Doc comments for classes or interfaces must include the @author tag. Only one name per @author tag in the form @author firstname lastname. Developers making major changes on the file must add their name. For methods or constructors the @param, @return, @throws, @see tag must be included as needed. Do not use the @exception tag. A package.html must be added for each new package.

For further details, see How to Write Doc Comments for Javadoc which includes information on the doc comment tags and for details about doc comments and javadoc, see the Javadoc Tool Home Page.

Compound statements are statements that contain lists of statements enclosed in braces { statements }. See the following sections for examples.

A return statement with a value should not use parentheses unless they make the return value more obvious/better readable in some way.

return list.size();
// OR
return (size != 0 ? size : DEFAULT_SIZE);

for (int j = 0; j < SIZE; j++)
{
    // ...
}

When using the comma operator in the initialization or update clause of a for statement, don't use more than three variables. If needed, use separate statements before the for loop (for the initialization clause) or at the end of the loop (for the update clause).

while (i > 0)
{
    // ...
}

Don't do any operations within the control element:

while (--i > 0);  // DON'T

switch (i)
{
    case HttpServletResponse.SC_ACCEPTED:
        // ...
        /* falls through */
    case HttpServletResponse.SC_BAD_REQUEST:
        // ...
        break;
    case HttpServletResponse.SC_CONTINUE:
        // ...
        break;
    default:
        throw new RuntimeException("Unexpected condition.");
        // no break here because position is unreachable!
}

Every time a case falls through (doesn't include a break statement), add a comment where the break statement would normally be to indicate that the fall-through is happening intentionally. This is shown in the preceding code example with the /* falls through */ comment.

Every switch statement must 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 default case should anyway always be the last to appear.

Four spaces should be used as the unit of indentation. Never use tabs. All indentation must be done using space characters.

Do not write lines longer than 80 characters, since they are not handled well by many terminals and tools.

Note: Examples for use in documentation should have a shorter line length (no more than 70 characters).

Break always before the keywords extends, implements and throws and indent a additional unit of indention (4 spaces).

public class IndentionSample
    extends SampleSnippets
    implements Serializable, Cloneable, Comparable
{   
    /**
     * 
     */
    public void doSomething (int length)
        throws IOException
    // ...

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

final SimpleBusinessResultException e
        = new SimpleBusinessResultException(
            ResultCode.SPLIT_AUTHORIZATION_SPLIT_INDEX_UNEXPECTED);

If the above rules lead to confusing code or to code that is squished up against the right margin, just indent 8 spaces instead.

If your code is so deeply nested, splitting the code into several methods might be a good idea. Also if your statement is much too long to fit in a line you might think about rewriting the code using several statements.

Blank lines improve readability by setting off sections of code that are logically related.

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

Two blank lines should always be used between sections of a source file.

Blank spaces must be used in the following circumstances:

The prefix of a unique package name is always org.jcoderz. and must match the regular expression ^org\.jcoderz(\.[a-z][a-z0-9]*)+$.

Subsequent components of the package name vary according to the teams own internal naming conventions.

Class names should be nouns, in mixed case with the first letter of each internal word capitalized and must match the regular expression ^[A-Z][a-zA-Z0-9]*$.

Try to keep your class names simple and descriptive. Use whole words - avoid acronyms and abbreviations (unless the abbreviation is much more widely used than the long form, such as URL or HTML), e.g. class Raster or class ImageSprite.

Use nouns to name interfaces that act as service declaration:

public interface ActionListener
{
    void actionPerformed (EventObject event);
}

Use adjectives to name interfaces that act as descriptions of capabilities. Most interfaces that describe capabilities use an adjective created by tacking an “able” or “ible” suffix to onto the end of verb:

public interface Runnable
{
    void run ();
}

public interface Accessible
{
    Context getContext ();
}

Interface names must, like class names, have the first letter (of each noun) capitalized.

Methods should be verbs, in mixed case with the first letter lowercase, with the first letter of each internal word capitalized: run(), runFast(), or getBackground().

Variables are in mixed case with a lowercase first letter, internal words start with capital letters. Variable names must not start with underscore _ or dollar sign $ characters.

Variable names should be short yet meaningful. The choice of a variable name should be mnemonic - that is, designed to indicate to the casual observer the intent of its use. One-character variable names must be avoided except for temporary throwaway variables. Common names for temporary variables are i, j, k, m, and n for integers; c, d, and e for characters.

Do not use local variable names that hide variables at higher levels.

The name of class members must start with a lowercase letter s and match the regular expression ^s[A-Z][a-zA-Z0-9]*$. The name of natural members must start with a lowercase m and match the regular expression ^m[A-Z][a-zA-Z0-9]*$.

public class MemberSample
{
    private static int sClassAccessCounter = 0;
    private int mMemberAccessCounter = 0;

    // ...
}

Names of variables that refer to collections of objects should correspond to the plural form of the semantic type contained in the collection. This enables a reader of the code to distinguish between variables representing multiple values from those representing single values:

private Object[] mCustomers = new Object[MAX_CUSTOMERS];

void addCustomer (int index, Object customer)
{
    mCustomers[index] = customer;
}

The names of constants must be all uppercase with words separated by underscores (_). Exception to this are the constants logger and serialVersionUID.

static final int MIN_WIDTH = 4;
static final int MAX_WIDTH = 999;
static final int GET_THE_CPU = 1;
static final long serialVersionUID = -7064645359225861305L;
static final Logger logger 
        = Logger.getLogger(SampleSnippets.class.getName());

Do not use an object to access a class (static) variable or method. Use a class name instead.

classMethod();
ReferringSample.classMethod();
anObject.classMethod(); // DON'T

Numerical constants (literals) must not be coded directly (magic numbers), except for -1, 0, and 1, which can appear in a for loop as counter values.

It is generally a good idea to use parentheses liberally in expressions involving mixed operators to avoid operator precedence problems. Even if the operator precedence seems clear to you, it might not be to others. Do not assume that other programmers know precedence as well as you do.

You should have only one exit point in a method. You must have a good explanation if you use more than one return statement in a method.

Use TODO in a comment to flag something that is bogus but works. Use FIXME to flag something that is bogus and broken.

Initialize local variables where they are declared. The only reason not to initialize a variable in its declaration is if the initial value depends on some computation that has to occur first.

Methods are limited to 100 lines of code. Empty lines and single line comments are ignored.

The number of arguments for an method or constructor must not exceed 7.

Intentionally empty block must contain a comment. Empty blocks that can/should never be reached like empty catch or default block must throw a RuntimeException.