eecs285.org

Coding Standards

Good code must be readable, maintainable, and make proper use of abstractions, in addition to behaving correctly. As such, we will be grading programming projects not just for functionality, but also for programming practices and style.

Style

We recommend adhering to common style guidelines, such as Google’s style guide for Java. We will not grade every aspect of style, but following a widely used set of guidelines will make your code more readable and maintainable.

The following are the specific requirements your code must follow:

Documentation

Documentation is necessary for others to understand the purpose of your code. We require the following comments in your code:

Programming Practices

Some projects will also be graded for programming practices such as making appropriate use of object-orientation and avoiding code duplication.

Functions

Functions should be short and have a single purpose. If you find yourself writing a long function, figure out a self-contained subtask and write it as a separate function instead.

Use functions to avoid duplicating code. If there are two places in your program that have very similar code, figure out a way to generalize it into a function (e.g. by introducing parameters) and then call that function from both places.

Object Orientation

When writing object-oriented code, make appropriate use of inheritance and polymorphism to avoid code duplication and hard-coding types. Code that is shared among several classes should be written once in a base class and inherited. Derived-class methods that add functionality to that of the base-class method should make a call to the base-class method (using a mechanism such as super) rather than duplicating code.

Method overriding should be used to customize behavior in a derived class, rather than type introspection (e.g. instanceof) or similar strategies followed by manual dispatch to custom code.

Always use the @Override annotation when overriding a method.

Instance variables must be private. Write getters/setters if other classes need access to the data.

Each top-level (i.e. non-nested) class must be defined in its own .java file.

Automated Style Checking

Some of the course projects use automated tools to enforce the style and programming-practice rules above. Style and documentation rules are enforced by checkstyle, while code practices, complexity, and duplication are checked by PMD. The following are sample configuration files used for these checks:

These files and the tools used are subject to change. The autograder for projects that use automated tools will provide the actual feedback used for grading.

If you install the automated tools on your own machine, you can run style checks as follows from the directory containing your source files:

$ checkstyle -c style.xml <files>
$ pmd pmd -no-cache -R practices.xml -d .
$ pmd pmd -no-cache -R complexity.xml -d .
$ pmd cpd --minimum-tokens 80 --files <files>

The XML configuration files above also must be in the same directory.

Since automated tools are not perfect, we will also grade aspects of style and programming practices by hand. Refer to the project specifications for the grade breakdowns.