Dalbey's Code Standards

Dr. Dalbey's Java Coding Standard

This standard is an extension to the Sun Java Coding Standard. Read the Sun Coding Standard first.

Here is a helpful QA checklist.

Exceptions to the Sun standard

The following five rules override the conventions in the Sun standard:

Open-close brace pairs must always be vertically aligned.
One character variable names are never allowed.
Avoid ternary expressions (if you don't know what they are, good.)
Omit "Beginning Comments" (Sec 3.1.1).
The else keyword should be vertically aligned under the corresponding if keyword.
Example:

// Does the discount rate apply?
if (quantity > kDiscountThreshold) { price = unitsOrdered * kDiscountRate; } // otherwise the standard rate applies else { price = unitsOrdered * kStandardRate; }

The remaining guidelines below are extensions to the Sun standard.

Declarations

Every identifier declaration must have an explanatory comment. Class-wide variables should use a javadoc style comment. Variables local to a method may use end-of-line comments. (Vertical alignment of comments is optional).

Example of "side-bar" comments:
char       reply;      // User's response
float      balance;    // Current account balance
DayOfWeek today;      // Current day of the week

Example of javadoc style comments:
/** The age of an employee in years */ Natural employeeAge;

Code Annotations

Comment any statement whose intent is not immediately obvious. Avoid comments that do not significantly enhance readability and comprehension.

All comments should be clear, grammatically correct, and use simple English phrases.

Comments should be meaningful and relevant. They should assist the reader in comprehending the code by adding helpful annotations. The comment should not simply restate the code.

BAD:
/* Repeat 7 times */
for (Day = 1; Day <= 7; Day++)

/* Process each day of the week */

for (Days day: Days.values())

A trailing comment after a close brace may be used to assist matching the closing brace with the corresponding open brace in IF statements, loops, classes, and compound statements. Examples are: "end if" "end class" "end loop"

The acronym "TODO" is commonly used to stand for "To Do" to indicate where required code has not yet been implemented. A "TODO" comment may be used to acknowledge that something is missing and needs to be completed later.

Naming Conventions

Identifiers must have meaningful names, i.e., names that convey as much information as possible about what the object is or what the process does. E.g., 'TotalPersons' is better than 'Count', and 'Row' is better than 'I'.

Choose names for different identifiers that are "psychologically distant" in order to avoid confusion. E.g., MaleTotal, FemaleTotal is better than Sum1, Sum2.

Nouns are used for types, constants, variables. Verb phrases are used for procedures and functions. For example,

Variables: person, carMake, hoursWorked

Data Types: DayofWeek, Currency, Temperature

Subprograms: readName, findAverage, isWinner

Constants: Use Netscape's standard: The first character is a lower case "k" followed by a mixed case name with no underscores. For example, kMaxTemperature.

Explaining your logic

Every control structure block (loop, decision, case, sequence block) has a descriptive comment on the preceeding line.

Example:

/* Does user want to continue? */

if (Reply == 'y')

Example:

/* Consider each letter in the name */

for (Letter=1; Letter < NameSize; Letter++)

Hint: A quick way to create these comments is to simply use the algorithm pseudocode from your detailed design.

Logic Structures

The for statement is used only for counting loops, never for event-controlled loops. The for statement conditional must always include all three parts (initialization, termination, increment).

Boolean Expressions

Never use a boolean constant in a boolean expression.
Example: if (someFlag == TRUE) should be if (someFlag)

Also, be sure to follow the Sun convention in Section 10.5.2.

Break and Continue

Never use break or continue (or return) in a loop.

Catch Blocks

Never use an empty catch block. The catch must do something, even if it is simply printing the stack trace.

Classes and Methods

Each class and each method must contain a header as described in the guidelines for high level design.

Java 1.5 Features

Use for-each loop to iterate over a collection.
Use enumerated types instead of "final static int" constants for enumerated values.
Use generics to specify the type of a collection at compile time.

Frequently Asked Questions

Can we use one-letter variable names for counting loops?
No. Give it a name that describes what you are counting.

Why no break in a loop? Why no multiple return stmts in a method?
It isn't structured programming.

Why braces vertically aligned?
Visually, it's easier to match open-close brace pairs when you eye tracks in a straight line.

    for .....
    {
       stmts
    }

NOT like this:

    for .....   {
       stmts
    }

Does the coding std apply to exams?
Not on a point by point basis.

Where are trailing comments useful?
On variable declarations, variable initialization, branches of a conditional (after else).

Why aren't constants all caps?
We don't need to shout the names of our contants at our readers.
View picture

Document History
1/8/2013 Added FAQ
6/15/2008 Added for-each and generics to Java 1.5 features.
11/4/2007 Omit section 3.1.1.
1/29/2007 JD Replaced TBD with TODO. Require enumerated types (since Java 1.5).
3/28/2006 JD "Comments are vertically aligned" changed to be optional. Identifier comments allowed to be javadoc-style or or end-of-line.
1/14/2004 JD Added clarification of position of else keyword.