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

Generally the Java built-in Logger class is enough for the need of the Okapi components.

private static final Logger LOGGER = Logger.getLogger(getClass().getName());

What level to use when logging:

Level	Usage
`SEVERE`	Errors the end user should see.
`WARNING`	Important alert messages the end user should see.
`INFO`	Additional log information, progress, etc. These messages are also shown to the user.
`FINE`	Extra, less important information. The end user may choose to see them.
`FINER`	Debug information. For developers.
`FINEST`	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.