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 Gradle, invoked by the Gradle wrapper. For a full build execute in the root directory (use gradlew.bat instead if you are on Windows):

$ ./gradlew.sh publishToMavenLocal

See build.gradle for the build configuration. All build related issues are to be handled by Gradle. The folder structure of the project follows the Maven standards, except that there are directories (called modules) allowing a multi-module project structure.

Logging

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

private static final 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 {
    // Code which may throw a checked exception
}
catch (final 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.

Code style

• Always use final for method parameters and exceptions. Fields and local variables should be declared final if possible. Aim for an assign-once style.
• Do not prefix fields and method invocations with this. The only exception are assignments in constructors and setters.

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 safe 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 Checkstyle configuration used is located in config/checkstyle.