design/coding.html (162 lines of code) (raw):
<html>
<head>
<title>Xerces 2 | Coding</title>
<link rel='stylesheet' type='text/css' href='css/site.css'>
</head>
<body>
<span class='netscape'>
<a name='TOP'></a>
<h1>Coding Conventions</h1>
<a name='TheProblem'></a>
<h2>The Problem</h2>
<p>
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
<em>attempt</em> at defining some basic coding conventions
for the Xerces 2 concept implementation.
</p>
<a name='Conventions'></a>
<h2>Conventions</h2>
<a name='Conventions.Comments'></a>
<h3>Comments</h3>
<p>
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.
</p>
<a name='Conventions.Whitespace'></a>
<h3>Whitespace</h3>
<p>
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.
</p>
<a name='Conventions.Names'></a>
<h3>Names</h3>
<p>
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.
</p>
<p>
<dl>
<a name='Conventions.Names.InterfacesAndClasses'></a>
<dt>Interfaces & Classes</dt>
<dd>
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.
<ul>
<li><strong>Good:</strong> StringBuffer XMLDocumentHandler</li>
<li><strong>Bad:</strong> stringBuffer XmlDocumentHandler</li>
</ul>
</dd>
<a name='Conventions.Names.Constants'></a>
<dt>Constants</dt>
<dd>
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.
<ul>
<li><strong>Good:</strong> WRONG_DOCUMENT</li>
<li><strong>Bad:</strong> wrongDocument</li>
</ul>
</dd>
<a name='Conventions.Names.Fields'></a>
<dt>Fields</dt>
<dd>
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.
</dd>
<a name='Conventions.Names.PublicFields'></a>
<dt>Public Fields</dt>
<dd>
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
<a href='design.html#QName'>QName</a> class.
<ul>
<li><strong>Good:</strong> type value</li>
<li><strong>Bad:</strong> fType</li>
</ul>
</dd>
<a name='Conventions.Names.LocalFields'></a>
<dt>Local Fields</dt>
<dd>
The letter 'f' is used as a prefix on fields with local
object scope. Acronyms are still capitalized as part of
the field name.
<ul>
<li><strong>Good:</strong> fStack fIANA2JavaMap</li>
<li><strong>Bad:</strong> uri</li>
</ul>
</dd>
<a name='Conventions.Names.StaticFields'></a>
<dt>Static Fields</dt>
<dd>
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 <em>all</em> instances of that class.
<ul>
<li><strong>Good:</strong> fgData</li>
<li><strong>Bad:</strong> data</li>
</ul>
</dd>
<a name='Conventions.Names.Methods'></a>
<dt>Methods</dt>
<dd>
Method names follow the camel-case rule.
</dd>
</dl>
</p>
<a name='Conventions.BlockStyle'></a>
<h3>Block Style</h3>
<p>
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:
<ul>
<li>All indent levels are 4 space characters</li>
<li>Opening brace on same line as start of block</li>
<li>Code is indented 4 space characters from start of block</li>
<li>Closing brace on separate line and aligned with start of block</li>
</ul>
</p>
<p>
Here is an example:
<pre>
for (int i = 0; i < 10; i++) {
// do something
}
</pre>
</p>
</span>
<a name='BOTTOM'></a>
<hr>
<span class='netscape'>
Author: Andy Clark <br>
Last modified: $Date$
</span>
</body>
</html>