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.

Checkstyle

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:

To run checkstyle on all Java files in the current directory:

java -jar checkstyle-6.2.2.jar *.java

To check the Javadocs in all Java files in the current directory:

java -jar checkstyle-6.2.2.jar -j *.java

To fully check your code you will need to run both checks above.

To see all available checkstyle options run java -jar checkstyle-6.2.2.jar without specifying a file to check.

Checkstyle Script

Download checkstyle-6.2.2.jar to your ~/bin directory. Create a file named checkstyle in your ~/bin directory with the following contents:

    #!/usr/bin/env bash

    java -jar ~/bin/checkstyle-6.2.2.jar "$@"

Then make it executable:

    $ cd bin
    $ chmod +x checkstyle

Now you can run checkstyle on any Java file like this:

    $ checkstyle Foo.java
    Audit done. Errors (potential points off):
    0
    $ checkstyle -j Foo.java
    ...

Style Guidelines

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
 * @version 13.31
 */
public class HourlyEmployee extends Employee {

    private double hourlyWage;
    private double monthlyHours;

    /**
     * Creates an HourlyEmployee with hourly wage of 20 and
     * monthly hours of 160.
     *
     * @param aName the employees offical full name
     * @param aHireDate the date on which the employee was hired
     */
    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 date 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;
    }
...
}