Visualization Group Coding Standards

By Jonathan Krentel

Version 1

5 November 2003

“All good software performs well. But great software, written with style, is predictable, robust, maintainable, supportable, and extensible.”

-The Elements of Java Style

The purpose of this document is to outline and specify the coding conventions that group members will adhere to in their source code development.

Developers are encouraged to look at The Elements of Java Style by Vermeulen et al. (Cambridge University Press). Most of the principles presented here are covered more fully there. Much of what is below is lifted directly from the relevant passages of this book. This book will serve as the common reference point on all Coding Style matters, and developers must notify the group if they deviate from this standard. The Coding Standard of the Decision Aid group is also acknowledged as a valuable reference.

1. General Principles

1. “When modifying existing code, adhere to the style of the original.”
2. “Adhere to the Principle of Least Astonishment. That is, avoid doing things that will surprise a user of our software.” Focus on:

1. Simplicity: “Build simple classes and simple methods.”

2. Clarity: “Ensure each class, interface, method, variable, and object has a clear purpose.”

3. Completeness: “Provide the minimum functionality that any reasonable user would expect to find and use. Create complete documentation.”

4. Consistency: “Similar entities should look and behave the same; dissimilar entities should look and behave differently.”

5. Robustness: “Provide predictable documented behavior to errors and exceptions.”

3. Do it right the first time. “More often than not, some pieces of prototype, [early version], or experimental code will make its way into a finished product, so you should anticipate this eventuality.”

The following principles are taken from the Decision Aid group coding standard.

2. Naming Principles

1. Class names should be meaningful.
2. Methods should be verbs. The preferred name for the method is self-documenting, i.e. it summarizes the functionality of the method.
3. Variable names should be meaningful.
4. Avoid omission of vowels.

3. Structure of Source files

A. All source files should begin with a block of comment that lists the class name, version information, date and author.

/**

* Classname

* Class description

*

*

* @version

*

* @author

*

*/

2. The first non-comment line of most Java source files is a package statement. After that, import statements can follow.
3. Order of variable declarations: First public, then protected then private. Variables come first in method bodies. Fields come before methods. Try to initialize variables at the place of their declaration.
4. Constructors are before methods. In general, abstract methods first, then public methods, then private. Methods should be grouped by functionality if possible.

4. Comment format

A. Each method should be preceded by documentation (javadoc) comments to describe its functionality. Documentation comments should be followed by a blank line to set them apart from the rest of the code, e.g.

/**

* Here is a documentation comment.

* Normally it is two lines long.

*

* @param hour the hour

* @return String the String expression of the time

* @throws Exception in the case of an invalid time

*/

public String toString( int hour ) throws Exception {

}

2. Important fields should have documentation comments
3. Important variables should have trailing comments

5. Method contents

A. Methods should be small

2. Parameter lists should be small

6. Braces and Indentation

A. Indent nested code by two spaces only.

2. Braces should open on the line where the introducing code is written, and should close at the same indentation level as that line, e.g.

for (int i = 0; i < n; i++) {

for (int j = 0; j < n; j++) {

//some code here

}

}