CIT 594 Style Rules
Spring 2012, David Matuszek

These are standard rules, not just “Dave’s rules.” Every rule has a purpose, usually either to improve program clarity or to help protect against error (or both). I will be happy to explain the reasons behind any of these rules; but to keep this page a reasonable length, I’m just stating the rules, not the reasons.

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;
Readingoffsite 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);
}

That is standard C and C++ style; it is not standard Java style.

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

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) { ... // space after "if", no space after "sqrt"

Never indent with mixed spaces and 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.

Readingoffsite 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 (use i for outer loops, j, k for inner loops); local variables used only over a very few lines of code (and whose meaning is obvious from context).

Don't abbreviate names

Common or easily understood abbreviations (such as max and min) are okay. Never abbreviate by leaving out letters, such as cmpatblty.

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.

Isolate side effects

If a method returns a value, it should not also have side effects (do I/O or make permanent changes in data). If the purpose of a method is to do I/O or modify data, it should return void. If a method must do both,

Exceptions: Many standard objects and methods violate this (Iterators, push and pop on Stacks, etc.) The important thing is to be very very clear when a method is doing both.

Methods should do either computation or I/O, not both

Exceptions: Methods that do I/O may do minor computations in order to properly format results. For debugging purposes, computational methods may temporarily include print statements, or they may include permanent print statements if they can be turned off by setting a flag.

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 and one are often exceptions 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.