# Okapi Framework - Developer's Guide ## Coding Guidelines
Glossary | Guide Content | Okapi Framework

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.