Style Guide for CS 159

The most important role of a set of coding standards is consistency. No group of programmers will ever completely agree on the best way to format code. Should code blocks be indented with tabs? With spaces? How many spaces? Two? Four? Eight? Where should opening braces be placed? The fact is, none of these things matter very much. What does matter is consistency. It is very inconvenient for a group of people to work together on a shared code base if they don’t agree on some set of common standards.

Rather than enumerating a long list of formatting requirements for this course we will use automated tools, both to confirm that formatting standards are satisfied and to automate the process of formatting our code. If you haven’t already, follow these instructions on Installing Java and Eclipse. This will walk you through the process of configuring Eclipse to use Checkstyle and the Eclipse Auto Formatter to satisfy the code formatting requirements for this course.

These tools are only useful for low-level formatting issues like indentation and line length. It is possible to write very bad code that is properly formatted and will pass automated checks. See below for some additional style requirements and suggestions.

Names

Selecting informative names is one of the most important steps in writing readable, maintainable and correct code. Variable names should clearly describe what the variable is intended to contain.

All names should be descriptive and readable: subTotal rather than s; grade rather than grd. Multiple-word names should use a capital letter to separate words (e.g. subTotal). Variable names should balance clarity with brevity. The name person is better than currentPersonObject. However, per is worse than either (percentage? person? permitted?).

Variable names should be nouns or noun phrases (e.g. studentName or subTotal)
Single letter variable are almost never acceptable, with exceptions of loop index variables and values in mathematical expressions.
Loop index variables should be named i unless the purpose of the variable suggests a more descriptive name. Nested loops should use j, then k.
Method names should be verbs or verb phrases (e.g. printLine or addColumn)

Comments

The point of comments is to clarify code that might otherwise be difficult for the reader to follow. Well organized Java code with informative variable names should require few comments inside of method bodies.

In-line comments must come before the code that they are describing or, if brief, on the same line following the code.
You must use normal English spelling and grammar. Phrases are okay, but cryptic abbreviations and unintentional misspellings are not.

Documentation

Every class must include a Javadoc comment like the following.

   /**
    * Overall description of the class goes here.
    *
    * @author Your name goes here
    * @version Vn -date (date may be in MM/DD/YY or MM/YY format)
    */

All methods (except simple getters and setters) must contain a Javadoc comment preceding the method header as shown in the example below. The description should describe the “black box” behavior of the method (what it does).

     /**
      * Overall description (black box behavior) of the method goes here.
      *
      * @param parameterName Describe each input parameter. You must have one
      * @param line for each parameter
      * @return Describe the value that this method returns.
      * @throws ExceptionName Describe under what conditions the exception may 
      * be thrown
      */

Acknowledgments

Every programming assignment must contain the following section which follows the class description or must cite any sources used (such as a TA). You should either include this statement in all files or minimally it may appear in the file containing your main method.

   /*
    * This work complies with the JMU Honor Code.
    * 
    * References and Acknowledgments: I received no outside help with this
    * programming assignment.
    */

    /*
     * This work complies with the JMU Honor Code.
     *
     * References and Acknowledgments: TA Glenn helped me with the 
     * foo method.
     */

This acknowledgment is not necessary for lab assignments. Note the single star after the slash: this is not a Javadoc comment.

Miscellaneous

Avoid “magic numbers”. Use named constants instead of literal values when you need to specify a constant value in your code. (e.g. Math.PI rather than 3.14159)

Your code must not have unused variables or unnecessary statements (statements that do nothing). Here is a typical example of a method that is catastrophically burdened with “do-nothing” code:

/**
 * Return the word at the indicated index, or null if there is no word at
 * that index.
 * 
 * @throws ArrayIndexOutOfBoundsException if the index is invalid.
 */
public String wordAtIndex(int index) {

    String result = null;

    if (index < 0 || index >= words.length) {
        throw new ArrayIndexOutOfBoundsException();
    }

    if (words[index] == null) {
        result = null;
    } else {
        result = words[index];
    }

    return result;
}

This code is functionally correct, and maybe it looks OK? It seems to satisfy the behavior described in the documentation. Here are some comments describing the problems with this implementation:

/**
 * Return the word at the indicated index, or null if there is no word at
 * that index.
 * 
 * @throws ArrayIndexOutOfBoundsException if the index is invalid.
 */
public String wordAtIndex(int index) {

    String result = null; // This assignment is pointless. result
                          // is assigned below and this default value
                          // can never be accessed.

    // This check is pointless. The same exception will be thrown
    // automatically if we attempt to access an invalid index.
    if (index < 0 || index >= words.length) {
        throw new ArrayIndexOutOfBoundsException();
    }

    // This conditional statement is pointless. If the array entry
    // contains null, then result will be assigned null in both the
    // if and the else blocks
    if (words[index] == null) {
        result = null;
    } else {
        result = words[index];
    }

    return result;
}

Here is an alternate implementation that has exactly the same functionality:

/**
 * Return the word at the indicated index, or null if there is no word at
 * that index.
 * 
 * @throws ArrayIndexOutOfBoundsException if the index is invalid.
 */
public String wordAtIndex(int index) {
    return words[index];
}

Avoid the use of break and continue except in switch statements.
All instance variables should be declared private or protected unless there is a documented reason for not doing so.
Class constants may be public if they are provided as a service to outside classes (such as Math.PI).
All visibility modifiers should be explicitly stated.
Avoid using * to import entire packages. (e.g. import utilities.GoodClass; instead of import utilities.*;)
Methods should not have undocumented side-effects. For example, print statements used for debugging should not be included in submitted code.
Unnecessary code repetition should be avoided. Create helper methods where they will simplify your implementation.