Introduction

This page defines guidelines and best practice when developing Java components for the SCAPE project. It has been defined as part of the initial functional review (MS17), however these guidelines are open for discussion, amendment and adaptation as appropriate.

The Guidelines are broken down into these sections:

Java

The following section provides guidelines for developing software using Java

Coding Standards

The long established Code Conventions for the Java Programming Language SHOULD be used. Written by the Sun developers (now Oracle), it's still a pretty good guide to producing readable, and maintainable code.

Anyone looking for a read that goes further than naming conventions, indentation, etc. might want to look at Effective Java, by Joshua Bloch.

Coding standards will be enforced by the builds at some stage in the near future. We're not planning to enforce all of the guidelines, but rather take stock of our current position and move forward pragmatically from there.

Comments

Please use them

Do avoid repeating the code though, instead try to document the approach used developing the function / algorithm and any quirks, or code that may be misleading.

We won't be getting worked up about code/comment percentages and the like as this simply encourages quantity over quality, when we're after the opposite.

This leads us nicely to JavaDoc.

JavaDoc

Good JavaDoc descriptions MUST be provided for all public classes and methods (beyond straightforward getters/setters) to help ensure maintainability and ease of development.

There are good resources from Sun/Oracle here:

• JavaDoc Home Page
• JavaDoc Style Guide

Developers using Eclipse may find it useful to turn on JavaDoc warnings.

Automated tools will be used for enforcement here.

Unit Tests

Up-to-date unit tests MUST accompany ALL non-trivial code.

If in doubt about the triviality of a method, save time wondering and write a test any way. If you're finding it hard to design or write a test for a particular piece of functionality, it probably means you don't fully understand what you're about to try to implement.

Unit Tests are good because:

• They help reduced bugs in new and existing features.
• Help improve design and facilitate re-factoring.
• Provide working examples for other programmers, and supporting documentation (though you remembered the JavaDoc, right?).
• Help those who may have to work on the code in the future.

We WILL be using tools to check test coverage - see Unit Test Coverage.

IDE Support

Eclipse users will soon be able to download a preferences file from this page that will enforce the Sun Java, and JavaDoc guidelines, by producing lots of warnings. It is a bit of a pain, and nobody has to use it, but it's a good start to getting a feel for how far your code is from production ready.

Other IDE users (IDEA, NetBeans, etc.), if you want to contribute any tools you have, then this is the place to get involved.

Maven

Wherever possible, Maven SHOULD be used to build Java projects. While it's not everyone's favourite tool it's conventions help to keep the project structures understandable to others, and it does help keep dependencies under control.

Enforcement of Coding Standards through Plugins

Maven represents our best bet of enforcing coding standards. Developers are free to use the tools of their choice, but everything in a Maven project has to come through the build at some stage. 

CheckStyle seems a good tool for ensuring Java coding standards adherance.  It is supported out-of-the-box by Maven, but there is also IDE support offering consistent enforcement from development to build for those who want it.

Unit Test Coverage

Maven Plugins for unit test coverage are also open for consideration. The two favourites here are:

• Emma - the older more established tool, but it seems in the process of been overtaken by
• Cobeturahttp://cobertura.sourceforge.net

Maven Site Build for Extra Information

ALL projects MUST be able to produce and publish a Maven Site (see Apache Maven Site Plugin). This can be trivially set up to produce the latest build report (including checkstyle, unit test stats, and dependencies).

Use of Maven Central

Mature projects SHOULD be published to Maven Central to allow others to add them as POM dependencies.

Projects SHOULD also consider publishing SNAPSHOTs, so that the latest version is always available for developers.