Code Quality and Style

This document outlines standards of code quality and code style which we would like to uphold in the Metafacture project.

Build Environment

We currently use Maven 3.0.4. For a full build call the package goal. To build a binary distribution call mvn clean package assembly:single. See /pom.xml for the build configuration. All build related issues are to be handled by Maven and Maven only (No extra qnt etc.). The folder structure of the project follows the Maven standards. The extra folder /quality_assurance which contains rule sets for static code analysis. modules is a placeholder for extensions.

Logging

We use the SLF4J framework and Log4j as a concrete logger. This means that in the code org.slf4j.Logger is used

private final static Logger LOG = LoggerFactory.getLogger(MyClass.class);

Exception Handling

The idea is to bail out as soon a possible when an error occurs. Consequently rethrow checked but fatal exception as runtime exceptions. Do not forget to add the original exception as cause. Otherwise the stacktrace is lost. In particular do not catch exceptions just to print a stacktrace! Let the virtual machine handle the stacktrace. Example:

try{
	???
} catch (Exception originalException) {
	throw new DomainSpecificException("Explanation", originalException);
}

DomainSpecificException inherits from RuntimeException. Throw IllegalStateException, IllegalArgumentException, etc. to indicate null pointers before they corrupt the system state. In performance critical parts use assert statements. They can be activated on demand with the VM switch -ea.

#Testing

Test Framework

JUnit is used. Tests reside in the src/test/java directory. Use the @Test annotation to mark test methods. Additionally, the method name should start with "test" (Maven issue).

public class ExampleTest {
	@Test
	public void testSomething(){
	[...]

To switch off tests use the @Ignore annotation.

Test Coverage

A test coverage report can be generated by calling the Maven goal cobertura:cobertura. Report location: target/site/cobertura/index.html

There is also an eclipse plugin for Cobertura: eCobertura, download at http://ecobertura.johoop.de/update/

Code Quality

Naming Convention

Please follow the official Java Code Conventions. Code Documentation Please document your code with JavaDocs. Especially leave a notice if code is experimental or not used. Also mention collaborating classes by adding @see and @link tags. Raw Types Do not use raw types. If unsure how to correctly generify or restore type safety, leave the raw type warning unsuppressed and place a TODO marker.

Compiler Warnings

Please avoid to commit code with compiler warnings. If warnings are unavoidable, suppress them with an annotation and add a short comment, why it is save to suppress it. If unsure about consequences add a TODO marker. Static Code Analysis Please do not commit code with FindBugs exceptions. The FindBugs plugin can be found at http://findbugs.cs.umd.edu/eclipse

Further plugins for code analysis:

• Checkstyle
• PMD

The rulesets used are located in folder /quality_assurance.