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:

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++)
  • 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:

    Example:
  • 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.