JavaCodingConventions
From Eigenpedia
Please see CodingConventions and GenericCodingConventions for language-independent rules.
Every so often, all Java source code is automatically standardized via the Jalopy source code formatter. You can minimize the effects by following the generic conventions as well as the example set by existing code.
Contents |
Package Descriptions
Every Java package must contain a package.html file describing its content. The first sentence of the file is incorporated into Javadoc package indexes automatically, so follow the Javadoc conventions carefully. See the Farrago Javadoc index for an example of this auto-indexing and the descriptions on existing packages.
Library and Language Features
Use modern versions of the Java collection classes (e.g. ArrayList and HashMap) rather than outdated versions (e.g. Vector and Hashtable), unless you actually need the synchronization provided by the older ones. Where possible, reference interfaces rather than classes, e.g.
public void createAndTransmitList()
{
List<String> list = new ArrayList<String>();
list.add("Flopsy");
list.add("Mopsy");
list.add("Cottontail");
transmit(list);
}
public void transmit(List<String> list)
{
...
}
This makes it easier to change the implementation choice later.
Use JDK 1.5. generics, enums, and enhanced for loops for better type safety and expression of intent.
(NOTE: JDK 1.5 language and library features are not allowed in client code. TBD: how you know when something is part of the client; right now there's very little such code.)
Idioms
Since we don't use m_ prefixes for member variables, use the pattern this.foo = foo for initializing member variables in constructors, e.g.
class Snafu
{
private final int calamityLevel;
Snafu(int calamityLevel)
{
this.calamityLevel = calamityLevel;
}
}
When inserting a reference to the SQL standard specification from a documentation comment, use this convention.
Imports
Always use collapsed imports (.*) except to resolve ambiguities. Imports are sorted automatically by Jalopy.
Tracing
See FarragoTracing.
Assertions
See discussion in farrago-dev archive.
