Administrivia‎ > ‎

SwEng Coding Style

This document introduces the Java code style conventions used in the SwEng assignments. They were inspired by the standard Java code guidelines, together with the Google Android project code conventions.

The conventions are specified as a Checkstyle configuration file, and can be downloaded from here. Please follow our tutorial to see how to use Checkstyle to verify your code. We will also use Checkstyle when grading the code style of your homework submission.

The rest of this document outlines the most important style rules present in the configuration file. Please note that this has an informative role only, and may not be fully accurate. The exact rules used for grading your work are ultimately determined by the Checkstyle configuration file.

General Conventions
  • Opening curly brace should appear on the same line as the previous statement. The closing curly brace should appear on a separate line.
  • Use braces even for single-statement blocks in if/else or for/while/do constructs.
  • Each variable declaration should happen on a separate line of code.
Variable Naming
  • Constant names should be capitalized, and individual words in the name should be separated by underscores (_).
  • Class names should have the first letter of each word capitalized.
  • Method names should have the first letter of each word capitalized, except for the first word, which should be lower-case.
  • Variable names should be formatted the same as method names.

    Examples

    public class MyClassName {
        public final static int CONSTANT_VARIABLE = 42;

        public void doSomething() {
            int myVar;
            ...
        }
        ...
    }

Handling Whitespace
  • Proper indentation. Each block of code should be indented one more level relative to the parent enclosing block. Each indentation level should be 4 spaces.

    Examples

    Good:
    public class MyClass {
        public static void main(String[] args) {
            if (args.size < 3) {
                System.out.println("Insufficient arguments.");
                return;
            }
        }
    }

    Bad:
    public class MyClass {
    public static void main(String[] args) {
       if (args.size < 3) {
         System.out.println("Insufficient arguments.");
        return;
     }
    }
    }

  • No TAB characters ('\t') are allowed in the source file. Instead, you should use 4 spaces for each indentation level. You should configure your text editor to use spaces when you press the TAB key. For Eclipse, go to Window/Preferences, then navigate to the General/Editors/Text Editors preference pane, and make sure the Insert spaces for tabs option is checked.
  • No trailing whitespace at the end of a line. Since the whitespace before the end of a line is hard to see, Checkstyle makes one's life easier by highlighting the whitespace.
  • Use spaces before and after arithmetic and assignment operators, in order to increase readability.

    Examples

    Good:
    z = (x + 1) * (y + 2);

    Bad:
    z= (x  +1)*(y+2);

Code Comments (Javadoc)
  • You should comment your code as much as possible. In particular, all public classes and public fields/methods need to have an associated Javadoc comment.

    Example

    /**
     * Performs processing on the data.
     * @param inputData The data to be processed.
     * @return The result of the processing.
     * @throws ComputeException If the data cannot be processed.
     */
    public int compute(int inputData) throws ComputeException {
        ...
    }

Code Size Limitations
  • Each line should be at most 80 characters wide. You can configure Eclipse to show this margin by going to Window/Preferences, then accessing the General/Editors/Text Editors preference pane. There, you should check Show print margin, and make sure that the value of Print margin column is set to 80.
  • Each Java file should have at most 2000 lines. If this file becomes larger, you should consider breaking the functionality in separate Java classes. You can configure Eclipse to show line numbers by going to Window/Preferences, then accessing the General/Editors/Text Editors preference pane. There, you should check the Show line numbers option.
  • Each method should be at most 150 lines long. If the method becomes larger, you should consider breaking the method functionality into multiple methods.
  • Each method should take at most 7 parameters. If you find yourself needing more parameters, you should consider, for instance, grouping the parameters into a larger object, pre-configuring the object before invoking the method, etc.
Imports
  • Avoid wildcard imports (e.g., import java.util.*;). Import only the classes that are used by the current compilation unit. In particular, Eclipse can manage the imports automatically for you, as shown in the Eclipse tutorial
  • Avoid illegal imports, such as the platform specific ones (sun.*). You may accidentally end up importing such classes if Eclipse finds a class with the same name in the sun package, and you don't select the correct one to import.
  • Group imports by package. The groups should be separated by an empty line. Eclipse does this automatically for you, if you let it add the imports automatically.
Good Code Practices
  • The object equals() and hashCode() methods should be implemented together. Never implement one without the other, or your code may break.
  • When comparing strings for equality, you should use the equals() method instead of the == operator.
  • Catch exceptions as specifically as possible. For instance, when a method may throw both IOException and FileNotFoundException, you should catch each of these in a separate catch block. Avoid catching general Exception or RuntimeException exceptions.
Comments