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:
The following section provides guidelines for developing software using Java
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.
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.
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.
What automated tools will we be using to enforce this?
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.
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.
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.
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.
Investigate the use of CheckStyle with Maven and Eclipse.
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
Investigate Emma and Cobetura unit test coverage tools (any others?), and decide which to go with.
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).
Add (or link to) an example showing how to set up a POM to build a Maven Site.
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.