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:
Developers using Eclipse may find it useful to turn on JavaDoc warnings.
Automated tools will be used for enforcement here.
![]() | ACTION What automated tools will we be using to enforce this? |
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.
![]() | ACTION Investigate the use of CheckStyle with Maven and Eclipse. |
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
- Cobetura
http://cobertura.sourceforge.net
![]() | ACTION Investigate Emma and Cobetura unit test coverage tools (any others?), and decide which to go with. |
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).
![]() | ACTION Add (or link to) an example showing how to set up a POM to build a Maven Site. |
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.