Development Guidelines for Java

Use Maven

There is no constraint over which development environment people use.
However, the build tool is Maven (3.x). So, use it.

Before every commit or pull request, run…

mvn clean install -P run-integration-tests

Git Commit Messages

This section is widely inspired (and partially copied) from Atom.io’s web site.

• Use the present tense (“Add feature” not “Added feature”).
• Use the imperative mood (“Move cursor to…” not “Moves cursor to…”).
• Limit the first line to 72 characters or less.
• Reference issues and pull requests liberally (with #<issue-number>).

• Optionally, consider starting the commit message with an applicable emoji.

  • :art: when improving the format or structure of the code
  • :racehorse: when improving performance
  • :bomb: when fixing a bug
  • :green_hart: when fixing the CI build
  • :heavy_check_mark: when adding tests
  • :lock: when dealing with security
  • :arrow_up: when upgrading dependencies
  • :arrow_down: when downgrading dependencies

Squash your Commits

Sometimes, and for whatever reason, it takes several commits to solve an issue.
To improve the readability and the history browsing, it is better to squash your commits when you can.

Squashing means merging contiguous commits into a single one.
Squashing should be ONLY be done on forks. They are acceptable on pull requests provided they have not yet been accepted (git push -force will be necessary then).

To squash your commits, we suggest you follow this very good tutorial from the web.

CheckStyle

Roboconf’s Maven configuration comes with a CheckStyle configuration.
Basically, it checks some casual rules about code quality. It also checks the well-formedness of Javadoc comments.

In particular, classes must be documented as follows…

/**
 * A brief and optional sentence describing the class (and ending with a dot).
 * <p>Additional (and still optional) information wrapped in HTML mark-ups.</p>
 *
 * @author the author's name - company name
 */

And methods must be described as follows…

/**
 * A brief and mandatory sentence describing the method (and ending with a dot).
 * <p>Additional (and optional) information wrapped in HTML mark-ups.</p>
 *
 * @param param1 an optional description
 * @param param2 an optional description
 * @return an optional description of the result 
 */

CheckStyle is also in charge of checking license headers in Java and XML files.
They must contain the headers for the Apache license. The copyright years are also checked.

SpotBugs

SpotBugs is the successor of FindBugs.
There is no default configuration for SpotBug in Roboconf’s pom.xml.
However, it is a good practice for developers to run this tool locally from time to time.

Using it with your IDE (such as Eclipse) makes it quite easy to use

Check Code Coverage

Even if it is not dramatic, keeping a high code-coverage is useful.
This indicator determines whether your unit tests check all the possible execution branches.

You can verify it in a given Maven module by typing in…

mvn clean cobertura:cobertura

Then, open the target/site/cobertura/index.html file in your web browser.

Rely on Utility Methods

roboconf-core contains several utility methods.
Take a look at the utils package and try to reuse these methods. This will prevent redundant code.

Running Sonar Locally

Roboconf does not have an online Sonar instance.
However, it is good sometimes to run it locally to get feedback and warnings about your code. Sonar brings information some other tools, like FindBugs and CheckStyle, do not have.

1. First, make sure you have Sonar installed on your machine.
   The easiest solution is Docker: docker run -d --name sonarqube -p 9000:9000 -p 9092:9092 sonarqube:lts-alpine
2. Go to Roboconf’s directory and execute the following commands.

mvn clean
mvn sonar:sonar -P sonar

See Sonar’s web site for more information.
You can now check out results on http://localhost:9000