wiki:Code Convention
Last modified 4 years ago Last modified on 05-08-11 14:20:47


General remarks on code formatting:

  • We use four spaces for indentation.
  • We always use curly brackets where possible.
  • We write out javadoc comments in sentences, and sentences always end with a period.
  • We create an internal link when referencing another class in the comments, but only the first time we reference it; for consecutive references we omit the {@link ...}.
package nl.nbic.convention.api.service;

import nl.nbic.convention.api.domain.SomeDomainObject;

 * This interface will define a number of methods to show the coding convention in action. The
 * first sentence of every javadoc comment block will be used in the generated API documentation
 * for the brief display. This goes for interfaces/classes, methods, and members. Therefor it is
 * important that the first sentence describes exactly what the class/method/member does, not more
 * or less then exactly that.
 * @author <a href="">Kees Burger</a>
public interface SomeServiceInterface {
     * Creates a new {@link SomeDomainObject} instance with default values.
     * @param id The identifier for this SomeDomainObject.
     * @return a new instance of SomeDomainObject, initialized with
     *     the given identifier.
    SomeDomainObject createSomeDomainObject(String id);

Remarks on interfaces:

  • We omit the visibility on methods in an interface because they default to public.
  • We omit the final modifier on parameters in interfaces because they are not forced onto the implementation.
  • We write interface and method documentation in code at all time.
package nl.nbic.convention.impl.service;

import static;

import nl.nbic.convention.api.domain.SomeDomainObject;
import nl.nbic.convention.api.service.SomeServiceInterface;
import nl.nbic.convention.impl.domain.SomeDomainObjectImpl;

 * Implements the SomeServiceInterface interface to show more of the the code style in action.
 * Same rules as stated in the interface concerning javadoc comments apply here.
 * @author <a href="">Kees Burger</a>
public class SomeServiceInterfaceImpl implements SomeServiceInterface {
     * The logger instance for this class.
    private static final Logger logger = LoggerFactory.getLogger(SomeServiceInterfaceImpl.class);
     * {@inheritDoc}
     * Implementation specific details like usage warnings can be appended to the comment by inheriting
     * the comment on the interface with @inheritDoc placeholder.
    public SomeDomainObject createSomeDomainObject(final String id) {

        final SomeDomainObjectImpl domainObject = new SomeDomainObjectImpl();

        return domainObject;

Remarks on classes:

  • The methods are ordered according to visibility: public, package, protected, private.
  • We will write class, method, and member documentation at all time.


General remarks on xml files:

  • We only include namespaces that are used in the document.
  • We use 4 spaces indentation in the xml document.








Remarks on POM files:

  • We will order the elements in the POM file according to the Maven guidelines.
  • We prefer to put all version values in the <properties> section, even when the version is only referenced once.
  • When using property placeholders for versions, we use <groupId>.version when the group contains a similar versioned modules of a framework, or <artifactId>.version when the group contains other projects which are independently versioned.
  • We explicitly define the scope of a dependency at all time, and we make it as appropriate as possible.
  • We don't use the system scope for dependencies.


<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="" xmlns:xsi=""
    xmlns:context="" xsi:schemaLocation=""

Remarks on spring context configuration files:

  • Use specific versions on the spring schemas.


# JDBC properties for the database service

Remarks on .properties files:

  • Always start the file with a comment block explaining the purpose of the file.
  • Group properties by separating groups with blank lines where it makes sense.
  • Each group should have an accompanying comment block explaning the purpose of the group.

IDE support

There are a number of plugins available to support and check the coding standards and/or test results.



NetBeans has built in support for Maven 3 and Plugins are available for Cobertura and Checkstyle. For comprehensive CI support consider installing the Software Quality Environment (SQE) toolchain from SQE NetBeans Update Center