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:

You must indent with spaces, not tabs. You should be able to setup
your IDE to use spaces. We suggest indenting 2 spaces, but more is
fine as long as you are consistent.

Your lines must be no longer than 80 characters.

All binary and ternary operators except . must be surrounded by a
space on each side.

Keywords such as if, for, or catch must have a space on either
side.

Use any style you like for curly
braces,
as long as you are consistent.

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 final and should be in all caps,
with words separated by underscores (ALL_CAPS).

Documentation

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.

We recommend using @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.

A comment for every private member describing its purpose. This does
not need to be in Javadoc format.

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.

Programming Practices

Some projects will also be hand-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)
followed by manual dispatch to custom code. Always use the @Override
annotation when overriding a method.