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 have consistent standards because you are working with other students.

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 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. Example:

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

Open braces usually go at the end of a line (consistency is required)

If you do this:

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

Please make sure you choose and follow a consistent style.  Some people like this style, but that is not the style the slides for this class use, which is like the following:

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

Also, 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 around binary operators (except dot), but not within parentheses

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.

Content rules

Read and follow the specification

When my assignment specifies class and interface names, and method names, parameters, and return types, don't change them. Don't change instance variables and methods to static ones. Doing so makes your program harder to grade. This is a practical issue for us.

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.

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 instance variable that doesn't describe the object shouldn't 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.

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.

Copyright © Harbor Mist, LLC 2007. All rights reserved.

Visitors: