CS 1331 Java Style Guide

Style is very important when writing code. Often code is not judged simply base on how effectively it performs a specific function, but also how easily it can be understood by a human reader. While rules of style vary, it is important to be able to learn to write code which conforms to a given standard.

In this class, the style rules that you are asked to follow are crystallized into an automated tool, called Checkstyle. This tool is configurable to check for a large number of different stylistic errors. Additional details about how to run checkstyle on your code can be found here.

The file you need to run Checkstyle:

In the simplest case, run checkstyle on your Java files like so:

java -jar checkstyle-6.2.2.jar MyJavaFile.java

For more advanced options (which will be necessary in later portions of the semester), check out the options available for running checkstyle. The rest of this document summarizes and in some cases clarifies Sun/Oracle’s Java Code Conventions (and in some places copies it directly) and the Checkstyle checks specified in cs1331-checkstyle.xml. The Checkstyle web site also documents each of its standard checks here: http://checkstyle.sourceforge.net/checks.html

Names

public class ClassName {
    public static final int SOME_CONSTANT;

    private int instanceVariable;

    public int getInstanceVariable() {
        return instanceVariable;
    }
}

Indentation and Line Length

//CONVENTIONAL INDENTATION
someMethod(int anArg, Object anotherArg, String yetAnotherArg,
           Object andStillAnother) {
    ...
}

//INDENT 8 SPACES TO AVOID VERY DEEP INDENTS
private static synchronized horkingLongMethodName(int anArg,
        Object anotherArg, String yetAnotherArg,
        Object andStillAnother) {
    ...
}
//USE THIS INDENTATION INSTEAD
if ((condition1 && condition2)
        || (condition3 && condition4)
        ||!(condition5 && condition6)) {
    doSomethingAboutIt();
}

//OR USE THIS
if ((condition1 && condition2) || (condition3 && condition4)
        ||!(condition5 && condition6)) {
    doSomethingAboutIt();
}
alpha = (aLongBooleanExpression) ? beta : gamma;

alpha = (aLongBooleanExpression) ? beta
                                 : gamma;

alpha = (aLongBooleanExpression)
         ? beta
         : gamma;

Declarations and Statements

int width;
int height

to

int width, height;
int foo,  fooarray[]; //WRONG!
class Sample extends Object {
    int ivar1;
    int ivar2;

    Sample(int i, int j) {
        ivar1 = i;
        ivar2 = j;
    }

    int emptyMethod() {}
    ...
}
if (condition) {
    statements;
} else if (condition) {
    statements;
} else {
    statements;
}

for (it i = 0; i < 10; i++) {
    statements;
}

while (condition) {
   statements;
}

do {
    statements;
} while (condition);

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

Javadoc Comments

Here’s a small example demonstrating proper Javadoc commenting:

import java.time.LocalDate;
import java.time.Month;

/**
 * Represents an employee who is paid an hourly wage.
 *
 * @author jdoe3
 */
public class HourlyEmployee extends Employee {

    private double hourlyWage;
    private double monthlyHours;

    /**
     * Creates an HourlyEmployee with hourly wage of 20 and
     * monthly hours of 160.
     */
    public HourlyEmployee(String aName, LocalDate aHireDate) {
        this(aName, aHireDate, 20.00, 160.0);
    }

    /**
     * Creates an HourlyEmployee with all required parameters.
     *
     * @param aName the employees offical full name
     * @param aHireDate the data on which the employee was hired
     * @param anHourlyWage this employee's non-overtime hourly wage
     * @param aMonthlyHours the number of hours this employee must work every
     *                      month
     */
    public HourlyEmployee(String aName, LocalDate aHireDate,
                          double anHourlyWage, double aMonthlyHours) {
        super(aName, aHireDate);
        ValidationUtils.disallowZeroesAndNegatives(anHourlyWage,
                                                    aMonthlyHours);
        hourlyWage = anHourlyWage;
        monthlyHours = aMonthlyHours;
    }

    /**
     * @return this employee's official full name
     */
    public String getName() {
        return "Hourly: " + super.getName();
    }

    /**
     * Calculates the monthly pay of this employee by mutiplying the
     * employee's hourly wage and monthly hours.
     *
     * @return this employee's monthly pay
     */
    public double monthlyPay() {
        return hourlyWage * monthlyHours;
    }
...
}