doc.developer.java-coding-conventions.html Maven / Gradle / Ivy
Coding Conventions - Java
Coding Conventions - Java
Latest update: 2007-03-27
See also Transformer Authors Code of Conduct.
Table of Contents
Inherited principles
This document inherits (builds upon) the general coding conventions as povided by Sun.
If not explicitly overriden, all conventions described in http://java.sun.com/docs/codeconv/ are to be considered a part of these Java coding conventions.
Design conventions
Use of patterns
Use of (GoF or other wellknown) patterns where justified and applicable, and adoption of wellknown names for the components of the patterns chosen, is considered good coding practice.
Not using (GoF or other wellknown) patterns where justified and applicable, or using patterns in distorted/skewed ways, is considered bad coding practice.
Exceptions
Packages where all members adress a common contract generally throw only Exceptions with package identity.
For example, any member of a package se.tpb.brailleformatter throws only Exceptions of type BrailleFormatterException through publicly exposed methods.
This is a exception wrapping princple which allows package-external components to more efficiently adapt behavior when an exception occurs.
Ensure that a wrapping Exception always returns a valid rootCause.
Under certain circumstances (meaning: when it can be assumed that a package-external component may benefit from it),
a wrapping Exception can be subclassed to provide severity or specificity information: for example,
se.tpb.brailleformatter.BrailleFormatterException can be subclassed into
se.tpb.brailleformatter.BrailleFormatterFatalException and se.tpb.brailleformatter.BrailleFormatterNonFatalException.
Internationalization and Localization
All strings that may or will appear in user interface layers are externalized.
Use the //$NON-NLS-1$ syntax to aid automated externalization processes.
Prefer the XML format of Properties in order to support Unicode.
To properly support non-BMP planes of Unicode, programmatically represent characters as ints, or where more appropriate, as char[].
Naming and syntax specifics
Class-wide (member) variables are prefixed with 'm'. Example:
public class PeekerPool {
private static Map mFeatures = null; //static features of a peeker saxparser
private static Map mProperties = null; //static properties of a peeker saxparser
private static PeekerPool mInstance = new PeekerPool(); //singleton instance
JRE Compatibility
If nothing else is explicitly stated for a particular project, code written should be compatible with the most recent and prior JRE released by Sun. In other words, there are normally two JRE versions that we are coding for compatibility with.
Documentation
All documentation is written using the english language.
Package-level documentation
Packages where all members contribute to a uniform contract have package-level documentation using the Javadoc package.html format. This document contains introductory information on the purpose of the package, and usage examples (using inlined pseudocode).
Class-level documentation
At the top of the class file (before any import statements) the following occurs:
- copyright statement
- license statement (if available).
Version information is not provided inline: we rely exclusively on repositories (CVS, SVN) to track and provide versioning and history information.
A Javadoc comment at the class-level describes the intent/contract of the class, using extensive {@link} and @see to provide contextual hooks.
The class-level Javadoc comment always contains @author.
All class member variables have a same-line inline comment defining them. Example:
public class PeekResult {
private String mInputSourceSystemId = null; //the path of the doc being peeked
private String mPrologPublicId = null; //first encountered public id, may remain null
private String mPrologSystemId = null; //first encountered system id, may remain null
private String mPrologXmlVersion = null; //XML version in xml declaration
Method-level documentation
Generally, all methods have a Javadoc comment, irrespective of visibility.
When a method is an implementation of an interface contract, the following approach is used:
- The formal javadoc comment is made on the interface.
- The implementing method explicitly references this interface method using this syntax:
/*
* (non-Javadoc)
* @see org.xml.sax.ContentHandler#skippedEntity(java.lang.String)
*/
public void skippedEntity(String name) throws SAXException {
}
(This comment can be autogenerated in Eclipse by doing /, *,ENTER).
Inline documentation
Use the TODO keyword followed by a comment to denote an improvable routine.
Use the FIXME keyword followed by a comment to denote an unfinished routine.
Debugging switches
Especially when implementing new components, add conditional debugging messages to critical parts of the new code.
Debug mode is set using a System Property flag. The most generic flag is org.daisy.debug. If nothing else has been decided for a specific routine, use this flag.
Always prefix the conditional debug strings with "DEBUG: ".
Always use System.out as the destination.
Example:
} catch (SomeException se) {
if (System.getProperty("org.daisy.debug") != null) {
System.out.println("DEBUG: SomeClass#someMethod SomeException");
}
Repository behavior
A repository commit always contains a detailed description of changes made to the committed class.
When committing a class where you made a fix or an append to someone elses work (i.e. you are not the author at class-level),
- comment out the old code (dont delete)
- attach an inline comment containing your initials/name, date, and describing the change you made
It is up to the discretion of the original author to clean out these commented out portions.
Example:
//mPeekResult.setPrologEncoding(locator.getEncoding());
//mPeekResult.setPrologXmlVersion(locator.getXMLVersion());
//mg 20050602: changed the above two setters, now using a cast:
try{
Locator2 locator2 = (Locator2) locator;
mPeekResult.setPrologEncoding(locator2.getEncoding());
mPeekResult.setPrologXmlVersion(locator2.getXMLVersion());
}catch (ClassCastException cce) {