A Java Style Guide

6. Tips and recommendations

In this section, we have compiled some recommendations that aren't part of the actual style guide, but have proven to lead to more readable source code if they are used.

6.1 Be consistent

There are a number of things that aren't regulated by this style guide, such as the number of empty lines between code blocks, if there is a space before or after parentheses, or if the left curly brace should be put on its own line or not. As long as you pick one style for these things and stick to it, it really doesn't matter which one you choose.

6.2 Imports

Qualify the imports, i.e. do not use the wildcard *, if only a few classes are imported from a package, otherwise it can be hard to understand why a package is imported. This is especially true for packages that contain classes for several purposes, e.g. java.util.

Another reason for not using wildcard imports is that new classes could be added to the package that might conflict with other classes you are importing. For instance, if you import both java.util.* and java.sql.*, you have two Date classes.

Qualifying imports can also speed up the compile time.

6.3 Variable declarations

Do not declare variables of different types on the same line even if it is syntactically correct to do so. The differences are easy to miss when scanning the code:

int aResult, aPositions[];

Also avoid declaring arrays using the old C style way with the brackets after the variable name, as in the example above. The array brackets are part of the type, not of the variable name, and should be put immediately after the type:

int[] aPositions;

Don't reuse a variable name inside a block of code if the same name is used outside of the block. Although the way scope is handled by the language is well defined, name reuse seldom leads to anything but confusion:

int aNumErrors;

if (...)
{
   int aNumErrors;
   ...
}

6.4 Statements

Put each statement on its own line. If there are multiple statements on a line, the ones to the right are easy to overlook.

Group statements that form a logical unit of a method by separating them from the rest of the code with empty lines. Code without these groups has a tendency to be a blurry mass of statements that is hard to penetrate.

Use parentheses extensively; don't be afraid to overuse them. All programmers aren't fluent in operator precedence and will be helped by code that is grouped by parentheses that aren't strictly necessary, like:

if ((a == b) && (c == d))

6.5 Magic numbers

Magic numbers are constant values used directly in the code, e.g.

if (aResult == 4711)

Don't use them, assign meaningful names to them instead:

if (aResult == kErrorWrongPassword)

Exceptions to this rule are "obvious constants", e.g. comparing to 0 to check if something is empty or testing for an even number by calculating its modulo 2 value.

6.6 Code blocks

If you intend to have the code continuing its execution in the next case inside a switch block, comment this explicitly to make it clear that you haven't forgotten a break:

case kCase1:
    doThis();
    doThat();
    // Fall through.

case kCase2:
    doTheOtherThing();
    break;
...

If a block of code is very long, it can be helpful to indicate the beginning statement at the closing right curly brace:

} // if (aNumArticles > 0)

Normally one should think again if a code block becomes so long that it needs a closing comment. However, when constructing for instance Java Server Pages, the mixture of HTML and Java code may produce code blocks that are long enough to make closing comments justifiable.

Contents