The home of Alitheia Core

Coding Style

In Alitheia Core development, we follow the Java coding style guidelines fairly strictly. The main exception is that we opt to substitute tabs with 4 spaces in order to ensure that the code will always look the same in all editors. We recommend to potential developers to configure their editors accordingly.

Documentation

The Alitheia Core tool makes good use of Javadoc in order to self-document the system. Good documentation standards are particularly important given the complex relationship between our components and the underlying OSGi-based Equinox framework. In general we follow the Javadoc style guidelines described here. Please familiarize yourself with these guidelines.

Below, we provide examples how code should be documented. These represent the most basic level of documentation expected within the SQO-OSS project:

Class Documentation

All classes within the Alitheia Core should provide a simple overview of the class' purpose within it's package.

/**
 * First sentence describing the class in a nutshel. What follows is extended documentation of
 * the class 
 *
 * @author Name Surname <email@host.com>
 */
public class Service {
}

Function Documentation

All functions within the Alitheia Core should provide details of the functions purpose in relationship to its class. In addition the following are also required (in this order):

• Input parameters (using @param tags)
• Expected results (using a @return tag)
• Thrown exceptions (using the @exception tag)

/**
 * Again, first sentence describes the method briefly. Use more sentences for more thorough
 * documentation.
 
 * @param fooClass the actual class of the fooObject. 
 * @param id the fooObject's identifier
 * @return the fooObject if a match for the class and the identifier was found,
 *          or null otherwise
 */
public <T extends Foo> T findFooById(Class<T> fooClass, long id);

Getters and Setters

There is no need to document the "get" and "set" methods used in JavaBean like classes. Instead, here, it is only important to ensure the class member variable is documented.