Formatting rules

Follow the style of the original

Consistency is important. When you enter an ongoing project, you should follow whatever style rules have already been established. In this class we will (mostly) be working alone, so this will not be an issue.

Indent controlled statements

Statements (and declarations) within a while, do-while, for, if, else, or switch should always be indented relative to the controlling statement. Our standard for this class (and Eclipse's default) is 4 spaces. Comments should be indented as if they were code.

Always use braces with control statements

If you leave out the braces because the control statement only controls one statement, this is inviting error when you later add statements to your code. Here's an example of the preferred style:

if (x < 0 || x > 100) {
    System.out.println("x is out of range: " + x);
}

An exception can be made for statements that fit on a single line, particularly if they don't perform any computations that affect subsequent code:

if (x < 0 || x > 100) return false;

Braceless if considered harmful

Open braces go at the end of a line

Don't do this:

if (x < 0 || x > 100)
{
    System.out.println("x is out of range: " + x);
}

Note that there should be a space before the opening brace:
if (x < 0 || x > 100) { ...

Exception: This rule doesn't apply to using braces to enter a literal array.

Put spaces just inside braces in a literal array

Example: String[] languages = { "C", "C++", "Java", "Ruby" };

Do not put spaces just inside parentheses

Example: hypotenuse = Math.sqrt(square(side1) + square(side2));

Put spaces around all binary operators except dot

Remember that = is also a binary operator.
Example: hypotenuse = Math.sqrt(side1 * side1 + side2 * side2);

Don't have lines longer than 80 characters

Break up long lines at reasonable places, such as after an operator or a parameter. If you must break up a long literal string, break it into two strings concatenated with the + operator.

Space after a keyword, but not after a method name

Usually you want a space before an open parenthesis, but not when it introduces a parameter list.
Example: if (Math.sqrt(x) < 100) { ...

Don't us hard tabs

Any good IDE will take care of this for you.

Don't overcomment or undercomment

Comment all and only those things which are not obvious from the code. Even better, if something isn't obvious from the code, rewrite the code so that the comment is no longer necessary.

Write Sweet-Smelling Comments

I completely agree with the above article. Nevertheless, everything declared public must have Javadoc comments, Public classes must have @author and @version tags, and public methods must include all relevant @param, @return, and @throws tags.

Content rules

Read and follow the specification!

When I tell you what to name your classes and interfaces, use those names. When I give you a method header, use exactly that method header. Don't change instance variables and methods to static ones. Don't change private variables to public variables. And so on.

Except as otherwise specified, implementation is up to you. Feel free to add private variables and private methods. You may also add public methods if (1) it makes sense to provide these methods to the general public, (2) you supply Javadoc for them, and (3) you have complete unit tests for them (when appropriate).

Don't repeat yourself (the DRY principle)

If you find yourself writing similar code in more than one place, try to make it into a method. (Note: Eclipse has a Refactor -> Extract Method command that you should learn to use.)

Use meaningful names

Exceptions: Indices of for loops; local variables used only over a very few lines of code (and whose meaning is obvious from context).

Instance variables should say something about the object

Instance variables describe the object. Any variable that doesn't describe the object should not be an instance variable; it should be a local variable, or maybe a parameter.

Each method and variable should have a single purpose

If you can't easily specify what a method does (or what a variable is used for) in a single sentence, you are trying to do too much with it.

Avoid long methods

If you find yourself putting in a comment to say what the next section of code does, see if you can change the comment into a method name, and put that section of code into a method with that name.

Don't use magic numbers

Almost all literal numbers should be defined as variables, often final variables. (Zero is sometimes an exception to this rule.)

Test all public methods

If you don't have a test for a public method, you should assume that the method doesn't work. (We will!)

Your "helper" methods should be private, unless there is a good reason for making them available to the user. Unfortunately, you can't write JUnit tests for private methods; such methods must be tested indirectly, by testing the public methods that use them. This isn't ideal, but that's the way it is.