What constitutes good programming style is somewhat subjective. These guidelines are largely Java-centric, but most of the principles apply equally to other languages.

See also:

Readability

Code should be easy to read.

  • use white space generously
  • use spaces rather than tabs, so that code display doesn’t depend on the reader’s tab settings
  • use indentation to indicate block structure
  • avoid long lines that may be hard to read on a narrow screen
  • pick a sensible style for formatting names
  • follow common conventions
  • do all of these consistently throughout the program
  • use auto-formatting tools, since they can do some of these for you

Clarity of Intent

It should be easy to understand what the programmer means.

  • try to write code that is as simple as possible
  • use meaningful names for variables, methods, classes etc
  • write Javadoc documentation for public methods, classes and packages
  • write internal comments where they are informative, but not just for the sake of it
  • don’t use ‘magic numbers’ that make the reader guess their significance; define as constants with meaningful names

Clarity of Structure

It should be easy to see how the different parts of the program fit into the whole.

  • break up long classes and methods into smaller ones
  • use braces even for single-line blocks, since it’s easy to misinterpret the structure otherwise
  • avoid deep nesting of loops and conditional tests
  • make fields and methods private unless they need to be accessed from other classes

Correctness and Maintainability

Don’t duplicate code. Doing so makes the program longer, and more importantly harder to maintain since one copy of the code might be changed and become inconsistent with the other.

  • factor out code duplicated in methods into a common method called by both
  • factor out fields and methods duplicated in classes into a superclass extended by both

Modularity

Write modular code. Different concerns should be handled by different classes, and where possible even different methods within one class. This makes code easy to understand and maintain, and it allows one to reuse existing code for new purposes. This applies also to the distinction between domain logic and I/O. A method that does a complicated calculation and also prints the result to a file cannot be reused for purposes that do not involve printing of the result.

Examples

A Full Class

Here is a class written in a common Java style, illustrating a number of the style guidelines. You won’t be penalised if you prefer a different style and use it consistently, but tutors know that this style is considered acceptable.

/**
 * This example shows how a thrown exception is passed back to the calling method, and
 * to the method that called that one, and so on until a catch clause is found or the main
 * method is reached.
 * 
 * @author 0123456789
 */
public class Example {

    public static void main(String[] args) {

        try {
            Example example = new Example();
            int amount = example.getAccountBalanceByName("John Mcleod");
        }
        catch (UnknownCustomerException e) {
            System.out.println("Couldn't find id for customer");
        }
    }

    /**
     * Gets the account balance for the customer with the given name.
     *
     * @param customerName the name of the customer
     * @return the current account balance of the customer
     * @throws UnknownCustomerException if a customer with the given name can't be found
     */
    public int getAccountBalanceByName(String customerName) throws UnknownCustomerException {

        int id = getId(customerName);
        return getAccountBalanceById(id);
    }

    private int getId(String customerName) throws UnknownCustomerException {

        // In a real implementation this would look up the name in an array, database etc.
        if (customerName.equals("Jane Smith")) {
            return 32576;
        }
        else {
            throw new UnknownCustomerException();
        }
    }

    private int getAccountBalanceById(int customerId) throws UnknownCustomerException {

        // In a real implementation this would look up the balance in an array, database etc.
        return -10;
    }
}

This example illustrates:

  • single spaces between most reserved words, identifiers and symbols
  • single blank lines between methods
  • ‘camelCase’ style for identifiers
  • indentation showing block structure
  • Javadoc comments for class and public methods
  • internal comments where necessary to clarify intent of code
  • if/else branches contained within braces even when a single statement
  • short methods
  • methods private unless they need to be used from outside the class

Comparing Values

Booleans

The following code fragment, testing the value of a boolean variable condition, is correct but inelegant:

if (condition == true) {...}

Since condition is boolean, you don’t need the equality check. This means exactly the same:

if (condition) {...}

Similarly, rather than

if (condition == false) {...}

it’s simpler to write:

if (!condition) {...}

Strings

This code fragment may give surprising results:

if (s == "hello") {...}

Depending on how s has been defined, the conditional block may not be executed, even if s does contain the characters hello. This is because the code is checking whether s is exactly the same string object as "hello". Instead, write:

if (s.equals("hello")) {...}

Assignment versus comparison

This fragment is valid but probably doesn’t do what the programmer intended:

if (condition = true) {...}

The conditional block will always be executed, regardless of the value of condition. This is because the = operator means assignment not equality, so this updates condition to the value true, and then uses that value in the comparison.

Simplicity

Nested tests

The double test in this example is unnecessary:

if (condition1)
    if (condition2)
        doStuff();

since the checks can be combined:

if (condition1 && condition2) {
    doStuff();
}

Note also the braces to make the control flow obvious even if indentation is changed.

Conditional boolean expressions

The code in this example is more complicated than it needs to be:

if (f1(i))
    return true;
else if (f2(i))
    return true;
else
    return false;

The explicit comparisons can be eliminated to give:

return f1(i) || f2(i);

Clarity of nested comparisons

A single cascaded comparison tends to be clearer than a series of nested comparisons, for example:

if (f1(i))
    return g1(i);
if (f2(i)) {
    if (i > 0)
        return g2(i);
    else
        return g3(i);
} else
    return g4(i);

is probably clearer as:

if (f1(i))
    return g1(i);
else if (!f2(i))
    return g4(i);
else if (i > 0)
    return g2(i);
else
    return g3(i);

Unnecessary variables

The code in this example is more complicated than it needs to be:

boolean val = true;
boolean stop = false;
while (i < n && !stop) {
    if (f(i)) {
        val = false;
        stop = true;
    }
    i++;
}
return val;

Both of the boolean variables can be eliminated by allowing the method result to be returned from within the loop:

while (i < n) {
    if (f(i))
        return false;
    i++;
}
return true;

Back to top

Last Published: 03 Oct 2024.