-
Notifications
You must be signed in to change notification settings - Fork 34
Code Quality and Style
This document outlines standards of code quality and code style which we would like to uphold in the Metafacture project.
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.
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);
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
.
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.
- Always use
final
for method parameters and exceptions. Fields and local variables should be declaredfinal
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.
Please follow the official Java Code Conventions.
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.
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.
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.
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 Checkstyle configuration used in located in config/checkstyle
.
Fix or Metamorph - you can choose between one of them. Fix is recommended for the most users.
Metamorph or Fix - you can choose between one of them. Fix is recommended for the most users.