Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Guidelines on Unit tests can be found in Old unit test guidelines.

Java Related

Coding style

Our overall coding style is based on Sun's guidelines The coding style was decided in 2014 to be the default Eclipse formatter setting (as of 4.4) with the following extensions:

IDE supported code styles

The general Java code style settings are defined in the ./eclipse-formatter-settings.xml file. This file can be imported by:

Eclipse: See Code Formatter Preferences.
IntelliJ:
 See IntelliJ IDEA 13: Importing Code Formatter Settings from Eclipse. Currently importorder is not imported, so these are maintain separatly in IntelliJ . IntelliJ can also export it codestyle, see Copying Code Style Settings.

Codestyles changes should be initiated in Eclipse and copied to other IDE's.

IDE defined code styles

...

additions:

  • Line width set to 120 characters (as Java is considered a bit too verbose for the default to work well)
  • Indentation is 4 spaces.  No tabs.

 

Source can be formatted by maven using

   mvn com.googlecode.maven-java-formatter-plugin:maven-java-formatter-plugin:format


Note: In order for IntelliJ and Eclipse to format sources interchangeably the import sorting order must be the same.  For simplicity we went with the Eclipse defaults.

All imports are declared explicitly unless there is more than 99 classes used in a package (so no * by default) - this has the advantage of being unambigious. We use the following ordering (empty lines included):

  1. import static *
  2. import java.*
  3. import javax.*
  4. import all other
  5. import dk.netarkivet.*

Other code styles

Codestyles changes should be initiated in Eclipse and copied to other IDE's.

Eclipse:

 

  • Use File->Import->General->Preferences to import eclipse-xml-settings.epf in build-tools/src/main/resources
  • Use Preferences->Java->Code Style->Formatter->[Import] to import eclipse-formatter-settings.xml in build-tools/src/main/resources

(README.txt in the root Maven project contains the latest instructions)

IDEA IntelliJ:

Headers

We add the following header to all our Java-files. This is done by using the maven-license-plugin. All headers can be updated by running the license:update-file-header

...

Or by running the ./precommit.sh script, which includes a step to update file heades.

Dependency injection

Classes should have all their external dependencies, including configurations, injected through the constructor. This allows the creator of the class to define the external dependencies, which is very relevant for testing purposes.

The dependencies should be access through provider classes allowing the creator to dynamically decide when instances should be created or reused. So a constructor example could be: NetarchiveSuite was designed in another age with a lot of central methods elsewhere being called to provide a given service.  It has since been learned that quality improves if it is possible to test individual components on their own without having the full system available, and a good way to do that in Java is to provide external dependencies explicitly in the class constructor, as it allows for providing exactly what is needed in the given situation.  

When conversion is complete, it may be realistic to use a dependency injection framework to make this easier to manage.  

An example:

Code Block
public JobSupervisor(Provider<JobDAO> jobDaoProvider, Provider<Long> jobTimeoutProvider) {

The Provider<X> interface provides a get() method returning X.  This allows for lazy initialization and/or providing an unknown number of X'es.

Further reading:

Other guidelines

Children Display

...

JavaDoc is strongly encouraged, as the code might explain what happens, but not the why; the JavaDoc must describe the intent of the function, including assumptions and invariants as well as expectations of the arguments.   Please add and improve as needed.

Logging

We use the apache.commons.logging framework for logging (currently version 1.0.4), which gives us one unified interface that can be realized with different underlying systems.

...