In general

There are two ways of constructing a software design. One way is to make it so simple that there are obviously no deficiencies. And the other way is to make it so complicated that there are no obvious deficiencies.

-- C.A.R. Hoare (cited in Bowen, "Ten commandments of formal methods")

Program code is read by two audiences: people, and compilers. Both must be satisfied. Write your code so that there are obviously no deficiencies. Complicated code always has deficiencies, they're just hard to find and hard to fix.

"Right" is more important than "fast"

First get it right, then maybe get it efficient.

Only make it efficient if efficiency is needed for that part of the code. But always make it right. Correctness is always needed for every part of your code. It is often the case that early effort spent making code efficient gets in the way of making it right, and frequently is thrown away anyway when the specification changes.

It is never appropriate to make it fast before making it right. After all, it's easy to write software that does the wrong thing quickly (if you are in a real hurry, just use the class below).

  public class FastButWrong {
    public FastButWrong() {  throw new RuntimeException();  }
  }

Align your code with what it does

The name of something should give the thing's meaning. Don't use short or cryptic or abbreviated variable names, except in the very few situations that are so hallowed by long usage that they are more clear than a long name. The ones I find acceptable are:
1. "cc" for the character (but there must be just one character that your program deals with at a time for this to be effective),
2. "j" and "k" for integer indexes (but there must be just one or two possible things being indexed), and
3. "pv", "cu", and "nx" for the previous, current, and next one (but there must be just one kind of thing that your program deals with in that region of your code).
Do rename your variables, methods, etc. if what they mean has changed — don't keep an old name just because it's tedious to change it.
More shorter methods are almost always better than fewer longer methods. Keep them simple. Choose your methods to be simple enough that each one's implementation can be obviously correct.
Write your code so that it presents the steps it performs in the order in which a person would naturally think about them.
It is often easier to implement a solution to a more general problem, than a solution to a smaller and more specific problem. The more specific problem can then be solved by the general solution.
Use appropriate design patterns; they save you trouble and make your code clearer, because you are reusing the thinking that other people have done, and that your readers might already understand.

In the very common case where the attributes of the class are the parameters of the constructor, use the same names for each, but with initial underscores for the parameters. Then mistakes are obvious.

  Formula left;
  Formula right;
  /**
    Constructs the disjunction of two subformulas.
    @param _left  The first  subformula.
    @param _right The second subformula.
  */
  public Disjunction(Formula _left, Formula _right) {
    left  = _left;
    right = _right;
  }

Javadoc comments

Write javadoc comments for every class and every constructor, method, and field of the class.
Write a package.html description for every package, and make it the overview that explains the concepts that describe the package and how those concepts fit together.
Use @param, @return, and @throws to explain what each method does.
Make your javadoc comments the specification of the interface to your code.
Write the javadoc comments for each interface general and appropriate enough to cover all the classes that implement that interface, and let each of the classes inherit the javadoc comments where appropriate.

Someone should be able to use your packages, classes, and methods correctly after reading just the javadoc description.

Make it easy to describe

If it is hard to come up with javadoc comments and variable/method/class/package names that clearly describe what your code is doing, then your code is probably either

doing the wrong thing, or
organized in the wrong way.

Try writing a simpler, clearer description. Instead of struggling to make the description match the code, write a clear description and make the code match that. Reorganize your design so that you can describe the components easily and simply.

Layout

These rules have a long history of helping people write better code.

Use blank lines to separate conceptual units in your code.
Line up things that go together. For exaample, if you have an "if" ladder with one or more "else if"s, put a /**/ comment after the first "if" keyword so the conditions are lined up, and use whitespace to line up other things that go together (like the braces, or like the parts of the @param comments in the example further down).
```
  if /**/ (null == result)       {  ...  }
  else if (0 == result.length()) {  ...  }
  else                           {  ...  }
```
Java (and most other languages) let you omit the braces for an if, else, while, or for that has jut one statement. But don't do it! Put the braces in anyway. The classical reason is that later someone will want to add a second statement, they will forget to put in braces, and the bug will be almost impossible to find.
```
  // NO!
  if (onlyOne) m = 1;  // this is bad
```
```
  // Yes.  Always use braces.
  if (onlyOne) {  m = 1;  }
```

Use the compiler's checks to the fullest

In comparing an lvalue with an rvalue for equality, always put the rvalue on the left; that way, if you or someone later puts "=" instead of "==", the compiler will flag a syntax error.
```
  // NO!
  if (ref == null) {  ...  }  // this is unwise
```
```
  // Yes.  Put the rvalue on the left.
  if (null == ref) {  ...  }
```
(An lvalue (pronounced "el-value") is an expression that can be on the left side of an assignment; a variable, or an expression that produces a variable. An rvalue (pronounced "are-value") is an expression that can only be on the right side of an assignment; a value, or an expression that produces a value.)
In general, write your code so that semantic bugs (which are hard to identify and fix) have to be expressed using syntax bugs (which the compiler catches and which are easy to fix). For example, use the type system to represent behavior (discussed further below).

Assertion checking

As you write your code, put in assertion checks for every condition you are assuming is true. A good rule of thumb is: if you realize you are assuming something while you are writing code, stop and put in assertion code that checks that the assumption holds at the point where your code assumes it and throws an informative exception if the assumption is violated. Assertion checks are always appropriate if:

the set of acceptable values for a variable is smaller than the set of possible values, or
the values of two or more related variables must have a specific relation.

At a minimum, write checks of incoming parameter and attribute values for every method.

Assertion checking is crucial for software whose external and internal interfaces are unstable, as is almost always the case in research projects.

Immutability is your friend

Where possible, make objects immutable. That is, design your classes so that the value of each object of a class is set when the object is constructed, and never changed. Taking two examples from java.lang, String objects are immutable, and StringBuffer objects are mutable. Strings are much easier to reason about and get right.

Researchers have long known that using immutable objects makes it far, far simpler to construct a proof of correctness for a program or an aspect of a program. More recently, the best practitioners have realized that it also makes it far, far simpler to understand and reason about your programs. That means they are easier to design, easier to write, and easier to debug. If an object is immutable, then you don't have to take its context and history into consideration, and context and history are the aspects that are the most difficult to understand and reason about.

My personal prejudices

There are several styles of bracing. Use this one:

  if (...) {
    ...
  }
  while (...) {
    ...
  }

If you indent with spaces, use two per level.

  if (...) {
    while (...) {
      ...
    }
  }

If you put a braced statement on a single line, put two spaces between it and the braces, both before and after.
```
  if (...) {  x = 2;  }
            ^^      ^^

  while (...) {  y += 5;  }
```

Unless you are using Eclipse, which controls javadoc formatting for you, indent your javadoc comments like so:

  /**
    Align the start and end markers with each other
    and the entity you are commenting.
  */
  public interface Javadoc {

    /**  Short ones can go on a single line (two spaces before and after).  */
    String oneLiners();

    /**
      Longer ones have the start marker on a line by itself,
      and the end marker on a line by itself.
      Text is indented two spaces further in.
    */
    String longerOnes();

  }

The Eclipse placement of a * at the beginning of each line is troublesome to do in a text editor and not worth the trouble.

In the common case of a "get" method that returns one of the class's attributes, use the same name for both.
```
  /**
    Returns the left subformula.
  */
  public Formula left() {  return left;  }
```
In the common case of a "set" method that sets one of the class's attributes, use the same names for everything. Prefix the parameter name with an underscore to distinguish it.
```
  /**
    Sets the left subformula.
  */
  public void left(Formula _left) {  left = _left;  }
```
Do not use "get" or "set" in your method names. Instead, fix the conceptual model you are using for the class, or the names you have given to the concepts. If it seems necessary to use "get" or "set" in order to distinguish the methods when searching the source code, then change to a capable text editor or development environment, or learn to use regular expression searching in your current editor.

The interplay between prototyping and testing

Testing is essential, but it's difficult to test code effectively if you don't know what it is supposed to do yet.

If you are in a prototyping situation, as is often the case in writing code for research projects, you should not spend too much time on writing tests. Just write tests for what you are pretty sure your code is going to have to do.

As the specification for your code stabilizes, add more tests. If your code is something whose correctness is going to be essential, then write a full set of tests when the specification settles.

Run your tests often, even early on when you don't have many.

Some interesting links

Bergin: Coding patterns

Thomas A. Alspaugh
Assistant Professor, Informatics Dept.
School of Information and Computer Sciences