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.
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
catch must have a space on either
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
Class and enum names must be in upper camel case (
Constants must be declared as
final and should be in all caps,
with words separated by underscores (
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.
@returntags 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.
Some projects will also be hand-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.
followed by manual dispatch to custom code. Always use the
annotation when overriding a method.