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 the Xerces 2 concept implementation.

Conventions

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 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

The naming convention for fields differ than the code in the standard Java libraries where each field starts with a lowercase letter and then uses camel-case for the field name. Subsequently, using these field names in code causes confusion as to whether a field is local to the method or global to the class. Because there are different types of fields, we have selected different types of conventions which are detailed below. When naming a field, follow the first rule that applies, with the rules appearing first in this list having more precedence.

Public Fields

When a class is designed to be used as a "structure" with public fields, follow the standard Java convention. For an example of a structure, refer to the QName class.

• Good: type value
• Bad: fType

Local Fields

The letter 'f' is used as a prefix on fields with local object scope. Acronyms are still capitalized as part of the field name.

• Good: fStack fIANA2JavaMap
• Bad: uri

Static Fields

Static fields are prefixed with an 'f' to denote that it is a field and a 'g' to denote that it's scope is global to all instances of that class.

• Good: fgData
• Bad: data

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
• 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
    }