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