Coding Standards

Guidelines Summary¶

This style guide is intended to help the computer professional produce better Java programs. It presents a set of specific guidelines for using the features of Java in a disciplined manner. The goal is to develop high quality, reliable, reusable, portable software. For a number of reasons, no programming language can ensure the achievements of these desirable objectives on its own. Programming must be embedded in a disciplined development process that addresses a number of topics in a well managed way. The use of Java is one of those. It must conform to good programming practices be based on well established software engineering principles. This style guide is intended to bridge the gap between these principles and the actual practice of programming in Java.

Clear, readable, understandable source text eases program evolution, adaptation and maintenance. First, such source text is more likely to be correct and reliable. Second, effective code adaptation is a prerequisite to code reuse, a technique that has the potential for drastic reductions in system development costs. Easy adaptation requires thorough understanding of the software, and that is facilitated considerably by clarity. Finally, since maintenance (really evolution) is a costly process that continues throughout the life of a system, clarity plays a major role in keeping maintenance costs down. Over the entire life cycle, code has to be read and understood far more often than it is written; the investment of effort in writing readable, understandable code is thus well worthwhile. Many of the guidelines in this style guide are designed to promote clarity of the source text.

This style guide is intended for those involved in the development of real software systems written in Java. Different roles in a software project can exploit the style guide in different ways. The programmer can use it as a reference on good Java style. It can be used in code reviews as a common reference. Finally, lessons learned in real projects can be captured by extending the style guide.

Class layout and comments¶

Files and filenames¶

Files longer than 2000 lines are cumbersome and should be avoided.

File names¶

The file must be named after the class it represents. As for most cases each file contains only one class, this is an easy naming convention. For nested or inner classes the name of the main class must be the name of the file. As names in Java are case-sensitive, the filename is case-sensitive also.

File organization¶

Each Java source file contains a single class or interface. Of course, this excludes inner classes as these must be defined without an (outer) class, and thus in the same file.

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.

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

Note that this comment part is not according to the JavaDoc style (See: How to write doc comments for JavaDoc - Sun Microsystems, Inc.) as this is file specific information that is not relevant in generated API documentation.

Package and import Statements¶

The first non-comment line of most Java source files is a package statement. After an empty line import statements can follow. For example:

package org.apache.felix.whatever.this.is;

import java.awt.Frame;
import java.io.InputStream;
import java.util.Vector;

A few notes must be made here: 1. Package rules. When not using an explicit package statement in your code the code still is in a package, the default package. This easily results in name clashes and as package naming should be a part of the design, always use an explicit package name. For naming rules of packages see 3.4 Naming conventions. 1. Import statements need to be explicit in order to overcome name clashes. They should be grouped by name. When the number of import statements of the same package exceeds the 'readability' limit (please use common sense), then import the complete package by adding '.*'. 1. Import order. First in this section should be the standard Java imports like: java.lang.Throwable. Second should be the Java extensions (i.e. javax), third, the third party stuff. Finally the project-specific imports should be added.

Class and interface Declarations¶

The following comment block is an example for the comment that belongs to the declaration of a class or an interface. The combination of JavaDoc syntax and keywords that are expanded by the source integrity tool result in the following block:

/**
 * This class is not really a class, because this file is just
 * a template that shows how the file header and class header
 * should look like.
 *
 * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
 */

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

Indentation¶

Four spaces should be used as unit of indentation. Use spaces or let your editor convert tabs to spaces as some editors might show the tabs different than they were intended! Tabs must be set exactly every 4 spaces.

Line length¶

There is no explicit limit for the length of a line. Make sure that the flow of the code is clear and that, when printing the file, it is well formed when using a reasonable font. A reasonable length would be around 80 characters.

Wrapping lines¶

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:

longName1 = longName2 * (longName3 + longName4 - longName5)
    + 4; // preferred
longName1 = longName2 * (longName3 + longName4 
    - longName5) + 4;

Comment¶

Comment styles¶

The Java language supports three different kinds of comments:

// text

The compiler ignores everything from // to the end of the line. Use this style when adding a description or some kind of explanation at the same line of code.

/* text */

The compiler ignores everything from / to /. The next documentation style is preferred.

/** Documentation. */

This indicates a documentation comment (doc comment, for short). The compiler ignores this kind of comment, just like it ignores comments that use / and /. The JDK JavaDoc tool uses doc comments when preparing automatically generated documentation (See: JavaDoc keywords and HTML tags). But JavaDoc only uses this documentation when it occurs at an expected position in the file like the class definition or a member declaration.

Block comments¶

Block comments are used to provide English descriptions of the contents of files, the task of methods and the description of data structures and algorithms. Block comments should be used at the beginning of each file and before each method. They can also be used in other places, such as within methods.

For a description of class comment see 2.1.3.3 Class and Interface Declarations. A method block comment looks as follows:

/**
 * Position the splitter location at a specified position.
 * This method can for instance be used when the last position
 * is stored as a preference setting for the user.
 *
 * @param position  New position of divider, defined in pixels
 *     from the left of the containing window
 * @see com.sun.java.swing.JSplitPane
 * @exception org.apache.felix.player.PositionException
 *     Whenever an invalid position is passed.
 */
public void setSplitterLocation(int position) throws PositionException

JavaDoc keywords and HTML tags¶

For class headers, method headers and member variables JavaDoc is used in order to generate API documentation from the source later on (See: JavaDoc homepage - Sun Microsystems, Inc.). A few specific JavaDoc keywords are:

Some HTML-tags that can be used in order to make the comment blocks more readable:

Note: there is no need to embed the parameter name in the @param tag in tags; this is done by javadoc automatically. The same holds for the exception name in the @exception or @throws tag. In the clarifying text however, use the tags when refering to parameter names etc. The example below shows the tag being used for the array parameter in the text, but not in its definition.

/**
 * Prints a range from an object array. The range
 * is specified by the first element to print, and
 * ranges to the last element of the array.
 *
 * @param array contains the objects to print
 * @param first index of first element in 
 *     the <code>array</code> to print
 */
public void printRange(Object[] array, int first)

// A familiar one:
public static void main(String[] args) {}
private static String m_lastCreated = null;
private static final int RED = 4711;

int level = 0;           // level where user enters the system
int horizontalSize = 0;  // horizontal size of current level layer

int level, horizontalSize; // level and size of current level layer

class ShipmoTrial extends Trial
{
    int m_index = 0;

    ShipmoTrial(int index)
    {
        m_index = index;
    }

    void emptyMethod() {}
}

// Do not use this
argv++; argc++;

if (condition)
{
    statement1;
    statement2;
}
else
{
    statement3;
}

if (condition)
{
    statement1;
    statement2;
}
else if (condition1)
{
    statement3;
    statement4;
}
else
{
    statement5;
    statement6;
}

switch (condition)
{
    case A:
        statements;
        // falls through here!!
    case B:
        statements;
        break;
    default:
        statements;
        break;
}

try
{
    statements;
} 
catch (ExceptionClass ex)
{
    statements;
}

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

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