Skip to content

Latest commit

 

History

History
87 lines (55 loc) · 3.7 KB

Code-Quality-and-Style.md

File metadata and controls

87 lines (55 loc) · 3.7 KB
Raw

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 4.0.2, invoked by the Gradle wrapper. For a full build execute in root directory

$ ./gradlew.sh install

respectively the gradlew.bat if you are on windows. 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 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{
	// Code which may throw a checked exception
} 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 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 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:

The rulesets used are located in folder /quality_assurance.