Coding Conventions

The Problem

As with any coding effort, there are always arguments over what coding conventions to use. Everyone thinks that they have the best style which leads to the entire source tree looking different. This causes consternation as well as eye fatigue on subsequent developers that need to maintain the code. Therefore, we are going to make an attempt at defining some basic coding conventions for myGrid.

These conventions are based on those used by the Apache Xerces 2 project.

Conventions

Boilerplate

Each Java source file shall contain a standard set of comments ("boilerplate") that contains information about copyright, authorship, license terms (see LicensingStuff) and version information,

See JavaBoilerplate for full details.

Comments

In general, code should be documented with comments. Complete javadoc comments should be used for interfaces and classes; constants; fields; methods; etc, regardless of their visibility.

Whitespace

Do not indent using tab characters -- they invariably display differently in everyone's editor or development environment. If your editor does this by default, then turn that feature off. Use 4 space characters for each indention level. Also, each line of code, with indentation, should not exceed 80 characters.

Names

The convention for names is pretty easy and follows the standard Java coding convention, except where there is no common convention. Unless otherwise stated, all names will follow the "camel-case" convention where the first letter of each word in the name is capitalized while the remaining letters are left lowercase (e.g. "camelCase"). Words in the name shall not be separated with underscore ('_') characters.

Interfaces & Classes

The names of interfaces and classes shall start with an uppercase letter and otherwise follow the standard camel-case convention. If a word in the name is an acronym, the acronym is left uppercase.

• Good: StringBuffer XMLDocumentHandler
• Bad: stringBuffer XmlDocumentHandler

Constants

Constant names are the one major place where the convention for names is not followed. The names of constants shall be written in uppercase, separating each word in the name with an underscore character.

• Good: WRONG_DOCUMENT
• Bad: wrongDocument

Fields

Field (instance and class variable) names follow the camel-case rule.

Methods

Method names follow the camel-case rule.

Block Style

Another controversial coding convention is the code block style. For the code in the Xerces2 implementation, it is agreed to use the following block style:

• All indent levels are 4 space characters
• Opening brace on same line as start of block (except as below)
• Code is indented 4 space characters from start of block
• Closing brace on separate line and aligned with start of block

Here is an example:

    for (int i = 0; i < 10; i++) {
        // do something
    }
    else {
        // do something else
    }
   

Class, interface and method headers can often be lengthy, with implements, extends or signature details extending over several lines. In these cases, the opening brace shall be on a separate line and aligned with start of the class, interface or method declaration.

Change Log

Revision 1.2

Added Boilerplate and Change Log sections

Removed requirement for using fVarName and fgVarName for fields with local object scope (instance variables) and static scope (class variables) respectively.

Modified position of opening brace in a class, interface or method declaration.

Revision 1.1

Taken from original Xerces 2 version by Andy Clark
Last modified: $Date: 2002/11/18 15:33:41 $