Java Code Style

Something to annoy everybody here - but in general consistency and readability is the aim. We're largely following the Sun recommendations but with some tweaks partially due to history and partially due to preference. Submitting code that conforms to the style set out here makes it much easier for developers to compare it to existing code and to see what has changed.

Indenting

2 characters - no tabs. If you use eclipse there's a plugin to convert all tabs to spaces. Look for "AnyEdit? tools" on Google.

Why 2 spaces? It's been that way a long time, eclipse handles it and changing all the source is pointless.

Blank lines

1 blank line is enough.

Layout

it's

if (expr) {
  statement;
} else {
  statement;
}

No spaces before ')' no spaces after '('.

Do not use

if (expr) statement else statement;

or any other variant. It's less clear than the bracketed form.

Width

Try to keep it within 72 to 80 - anybody remember why 72 and 80? Some of us are old enough. Align parameters under each other etc etc.

Imports

Within groups sort alphabetically. Ordered as follows

1. org.bedework
2. edu
3. net.fortuna (ical support)
4. java
5. javax
6. org
7. com

Remove (or comment out) all unused imports.

Method and field ordering

Keep the class ordered:

1. Fields
2. Constructors
3. public
4. protected
5. private

Unused code

Try to keep it to a minimum. Eclipse will report all unused code - the ideal is zero messages. The practical is probably about 15-20.

conditional expression a ? b : c

Please don't. They are even frowned on by the certification book.

Setters and getters

The conventions is set before get - unfortunate that eclipse does it the other way but we already have a lot. Setters and getters are just about completely self documenting though the comment could say what the property is if it's not obvious (it usually is). Name the set parameter "val" and we have nice concise code:

  /** Set the description for this thing
   *
   * @param val  String description
   */
  public void setDescription(String val) {
    description = val;
  }

  /** Get the description for this thing
   *
   * @param val  String description
   */
  public String getDescription() {
    return description;
  }

Use the Setters and getters

Not so much a code style thing but very important. In the hibernate world (and many others like it) byte-code is injected into the classes to set property values. If you refer to the property directly other than in the getter or setter you can avoid triggering the fetch so you might get a null value instead of the actual db value.

Exception bad, Throwable good

There are whole classes of exception which throw Throwable rather then Exception. Catch these and wrap them othewise we can cause problems in the server environment, especially in the j2ee world.

Many exception classes bad - few good

This refers to the throws clause of methods. Listing large numbers of exceptions does not help.

It is possible to define an exception class for every type of exception that might occcur: it doesn't help much in the end. One exception per project is enough. The usual response to an exception is to report it and give up. Recovery is hard to impossible. Related to all of this is the j2ee behavior of terminating any session that throws an undeclared exception. At the session interface we have to declare all exception classes thrown. The fewer the better.

Subclasses of a global package exception class are not included in this. They are useful for identifying which particular exception was caught - for example access denied exceptions.

Do NOT swallow exceptions

Always report in some way - do NOT continue - rethrow the (wrapped) exception or recover. If you cannot figure out what to do then FAIL and let somebody else figure it out.