Code

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="mailto:kees.burger@nbic.nl">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 com.google.common.base.Preconditions.checkNotNull;

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="mailto:kees.burger@nbic.nl">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.
     */
    @Override
    public SomeDomainObject createSomeDomainObject(final String id) {
        checkNotNull(id);

        final SomeDomainObjectImpl domainObject = new SomeDomainObjectImpl();
        domainObject.setId(id);

        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.

Configuration

General remarks on xml files:

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

POM

<project>
    <modelVersion>4.0.0</modelVersion>

    <parent>...</parent>

    <groupId>...</groupId>
    <artifactId>...</artifactId>
    <version>...</version>
    <packaging>...</packaging>

    <name>...</name>
    <description>...</description>

    <properties>
        <org.foo.bar.version>1.0</org.foo.bar.version>
    </properties>
    
    <dependencies>
        <dependency>
            <groupId>org.foo.bar</groupId>
            <artifactId>bar</artifactId>
            <version>${org.foo.bar.version}</version>
            <scope>compile</scope>
        </dependency>
    </dependencies>

    <build>...</build>
</project>

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.

Spring

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:context="http://www.springframework.org/schema/context" xsi:schemaLocation="
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-VERSION.xsd
        http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-VERSION.xsd"
    default-init-method="init">
</beans>

Remarks on spring context configuration files:

  • Use specific versions on the spring schemas.

.properties

# JDBC properties for the database service
jdbc.driver=com.mysql.Driver
jdbc.user=root
jdbc.pass=daisy
jdbc.host=127.0.0.1
jdbc.db=foo

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.

Eclipse

NetBeans

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