Coding Style

In the development of these open source projects we've stayed pretty close to the "standard" Java coding style seen in the libraries. There are some significant differences we've found worthwhile, though. If you're interested in contributing code to any of the projects please try to keep your changes compatible with the style of the original code. Some of the style choices are arbitrary, but following them consistently makes the code far more readable than otherwise.

Embedded Spaces

Do not use a space before the opening left parenthesis of an argument list or before the first argument in the list. Do use a space after each comma separating arguments in the list. Also use a space after every Java keyword, but not after a cast:

    public int anyMethod(Object object) {
        if (object instanceof String) {
            String name = (String)object;
        }

for instance.

Tabs, Indenting and Wrapping

Always use space character for indenting rather than tabs, and always use four spaces per level of nested brackets. Keep line lengths no more than 80 columns. When wrapping a line, use four additional spaces (one level) for indenting the wrapped text.

Variable Naming

In order to distinguish between different types of variables, prefix static (class) variables with "s_" and member (instance) variables with "m_", using mixed case for the remainder of the name (first word in name all lower case, then initial caps for additional words, if any).

Static final variable names use the Java library convention of all caps, with underscores ("_") to separate words within the names.

Try to keep local variable names as short as possible while keeping them meaningful, and use all lower case for these names (stringing words together with "_" characters if really necessary). Define local variables at the point of first use, not at the beginning of a block.

Use of Brackets "{}"

Always use brackets around the body of a conditional statement or loop, even if there's only a single statement in the body. In other words, do:

    if (whatever) {
        count++;
    }

rather than:

    if (whatever)
        count++;

or even:

    if (whatever) count++;

This pads the code a little, but avoids the potential for someone adding code along these lines:

    if (whatever)
        count++;
        also--;

and then taking entirely too long to figure out why the added statement is executed even when the condition is false.

Use the Java-library approach of appending the opening bracket to whatever defines the block (the method signature, if, while, or for statement, catch clause, etc.), as shown in the example at the start of this page. Start a separate line for the closing bracket, and indent it to the same depth as the statement that defined the block.

When chaining statements together this approach just applies the same principles:

    if (whatever) {
        count++;
    } else {
        count--;
    }

or

    try {
        something();
    } catch (Exception ex) {
        // do something here
    }

for instance.

The only exception to the opening bracket on the same line as whatever defines the block is for class definitions. These use the approach:

public class mine
{
    // ...
}

Comments and Documentation

Use inline comments ("//" lines) to narrate the work being done by the code for any code blocks longer than a few lines. Indent the inline comment to the same level as the code, and use a blank line before the comment to emphasize the blocking.

Use JavaDoc comments ("/** ... */" blocks) for all classes, methods, and non-local variables. The only exception is when a number of static public final definitions are used to define constants, and the names of the constants describe their purpose.

Always make sure the comments are kept current - out of date comments are worse than no comments at all, and code without comments is close to worthless.