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.
Fall 2021
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:
You must indent with spaces, not tabs. You should be able to setup your IDE to use spaces. Use 2 spaces for indenting statements within a block. When breaking a statement across multiple lines, each line after the first must be indented at least an additional 2 spaces.
Your lines must be no longer than 100 characters.
No star imports allowed (e.g. import java.util.*;).
All binary and ternary operators except . must be surrounded by
whitespace (a space or newline) on each side.
Commas , must be followed by whitespace.
Keywords such as if, for, or catch must have whitespace on
either side.
Curly braces { } must have whitespace on either side. The
opening curly brace { must be at the end of a line, in keeping
with common Java style guidelines (see
Google’s,
for example). The closing curly brace } must be on its own line,
unless it is followed by a comma , or a component of a compound
statement (else, catch, etc.).
The body of a compound statement such as an if or for must be
surrounded by curly braces.
Each statement must be on its own line.
Each variable must be declared in its own statement.
Names must be meaningful (i is fine for a counter).
Method and non-constant variable names must be in lower camel case
(lowerCamelCase).
Class and enum names must be in upper camel case (UpperCamelCase).
Constants must be declared as static and final and should be in
all caps, with words separated by underscores (ALL_CAPS).
The text SuppressWarnings or NOPMD may not appear anywhere
in your source code.
Documentation is necessary for others to understand the purpose of your code. We require the following comments in your code:
A Javadoc comment at the top of every .java file describing the
purpose of the file.
A Javadoc comment for every non-private member of a class describing the purpose of the member.
@param and @return tags for methods, but
we do not require them, as long as you explain the purpose of
each parameter and what the return value is.Inline comments for pieces of code that are unclear.
Do not comment obvious things such as “loops from 0 to size - 1.”
Write comments for code that you would have a hard time figuring out if you were to look at it in a month, or a year later.
Some projects will also be graded for programming practices such as making appropriate use of object-orientation and avoiding code duplication.
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.
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.
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.