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.

Test methods should be short and specific.
The tests should be be fast to run.
The tests should defined so they can be ran from a single location.

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.