Java Coding Conventions and Standards

| Naming | Curly Braces | Indentation and Whitespace | Comments | Miscellaneous |

Naming

Choose your names carefully. As part of program documentation, names must clearly indicate both the kind of thing being named and its role in the program. Whenever possible, write short, obvious names for very local contexts (i.e., a for loop counter could be called i) and longer names for bigger contexts (examples to follow). Avoid cryptic abbreviations (e.g.,use incrementEventCount() rather than incEvCnt()). Avoid choosing similar names for different things, e.g., index, indx, index2; or, on the other hand, similar names for very different things (example: if keys[] is a array of strings, then don't use key for an integer for loop counter).

Curly Braces

Curly braces delimit the bodies of classes, methods, and loops. There are two standard formats for braces, either of which is acceptable:

1. Curly brace goes at the end of the line that starts the class, method, loop, etc., and the closing brace is on a line by itself, lined up vertically with the start of the first line:

public class SomeClass {
    ... 
    public SomeClass() { // Constructor
    ... 
    } 

    public int someMethod(int n, float m) {
        ... 
        for (int i = 0; i < someField; i++) {
            ....
        }
        ...;
    }
}

2.Each curly brace is on a new line, and a pair is lined up vertically. The previous code in this format would look like this: 

public class SomeClass
{
    ... 
    public SomeClass()
    { // Constructor
        ... 
    } 
    public int someMethod(int n, float m)
    {
        ... 
        for (int i = 0; i < someField; i++) 
        {
            ....
        }
        ...;
    }
}

Indentation and Whitespace

The placement of syntax on the page is one of the most important aspects of style and readability, and has three aspects: horizontal placement is achieved by (i) using spaces or tab stops to indent lines of code and other similar items (such as variables in a series of declarations), (ii) for inserting "oxygen" around operators and punctuation, and vertical placement is achieved by (iii) inserting blank lines to separate classes, members of classes, and regions of code with various purposes.

The usual standard for indentation is to

Example: 

public class SomeClass {
    private int someField; 
    private double anotherField; 
    public SomeClass() { // Constructor
        someField=1;

        anotherField = 3.14; // Initialize all fields
    } 
    public int someMethod(int n,float m) {
        int localVariable=0; // Must initialize local variables
        float anotherLocalVariable=1; // This one too
        localVariable=n-2;
        anotherLocalVariable=localVariable+m*3; 
        for(int i=0;i<someField;i++) {
            localVariable=localVariable*2;
            localVariable=localVariable-someField;
        }
        return localVariable+n;
    }
}

This example is not in fact very readable, as it it hard to parse the structure of the individual lines; the usual standard for increasing readability of each line is:

This example should thus be written as: 

public class SomeClass {
    private int someField; 
    private double anotherField; 
    public SomeClass() {                   // constructor
        someField = 1; 
        anotherField = 3.14;              
    } 
    public int someMethod(int n, float m) {
        int localVariable = 0;             // must initialize local variables
        float anotherLocalVariable = 1;    // this one, too
        localVariable = (n - 2);
        anotherLocalVariable = localVariable + (m * 3); 
        for (int i = 0; i < someField; i++) {
            localVariable = localVariable * 2;
            localVariable = localVariable - someField;
        }
        return localVariable + n;
    }
}

Still too crowded! For vertical arrangement, simply 

public class SomeClass {
    private int someField;
    private double anotherField;

    public SomeClass() {                    // constructor
        someField = 1;
        anotherField = 3.14;                
    }

    public int someMethod(int n, float m) {
        int localVariable = 0;              // must initialize local variables
        float anotherLocalVariable = 1;     // this one, too

        localVariable = n - 2;
        anotherLocalVariable = localVariable + m * 3;

        for (int i = 0; i < someField; i++) {
            localVariable = localVariable * 2;
            localVariable = localVariable - someField;
        }

        return localVariable + n;
    }
}

Comments

Comments should help the reader of your code to understand it. They may help YOU to understand it if you need to rework your code at some later point. In the case of a programs submitted for a course, they also serve to convince the grader that you grasp the what, how and why of your code (as opposed to having hacked it into working). Like any other form of expression, it should not be flowery or repetitive. In particular, please observe the following guidelines:

Miscellaneous

Keep Line Lengths Under 80 characters

On many machines and in many software packages, this is a standard line length. It makes it easier for others (like graders) to read and/or print your programs. If your parameter list for a method is too long to fit within 80 characters, then insert line breaks and indent the remaining lines of parameters:

public boolean calculateAverageDailyReturn(int customerID, double dailyBalanceForMonth[], double dailyInterestRate, double discountRate) 
{
should be rewritten as: 
public boolean calculateAverageDailyReturn(int customerID, double dailyBalanceForMonth[], 
    double dailyInterestRate, double discountRate) 
{
If your println() statement is too long, then you should break this up as well, using the + operator to concatenate strings: 
System.out.println("The average daily return for customer " + customerID + " at the discount rate " + discountRate + " is " + A);
should be rewritten as: 
System.out.println("The average daily return for customer " + customerID +
    + " at the discount rate " + discountRate + " is " + A);




Written by: Wayne Snyder (Fall 2004)

Updated: Alexandra Stefan (Spring 2006), Dave Sullivan (Fall 2006)