Okapi Framework - Developer's Guide

Coding Guidelines

When coding a component of the framework, try to respect the following guidelines:

Coding Style

Generally use the Java classic conventions described at: http://java.sun.com/docs/codeconv/ 

Exceptions

Checked exceptions are often not well suited for a component-based system like the Okapi Framework. Avoid them when possible.

When throwing exceptions, if possible use the appropriate common exception defined in the net.sf.common.exceptions package.

If you have a need for a new type of exception and use it in different packages, add it to the set of common exceptions. If that exception is specific to a package, declare it within that package.

Logging

All Okapi components use SLF4J for logging. This allows server side users to bind to the prefered logger, even implementing their own.

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

private final Logger LOGGER = LoggerFactory.getLogger(getClass());

For the decision to use non-static loggers see this discution.

What level to use when logging:

Level Usage
FATAL Very severe error events that will lead the application to abort. Since Okapi is used server side we should probably never do this.
ERROR Errors the end user should see.
WARN Important alert messages the end user should see.
INFO Additional log information, progress, etc. These messages are also shown to the user.
DEBUG Extra, less important information. The end user may choose to see them.
TRACE Debug information. For developers.

Unit Tests

Most classes of the framework should have a corresponding JUnit test class that exercise most of its methods.

Java Documentation

All Classes, public and protected methods should have comprehensive JavaDoc comments. Java packages may optionally have JavaDoc by including a package.html file.