Java Style Guide

Documentation in the source program

Each class will be preceded by a javadoc style comment:

/**
 * <code>ClassName</code> description ...
 * <p>
 * @author  author
 * @version version, date
 */asdf

class ClassName

Make sure that there are no blank lines of other comments between the javadoc comment and the class code.

The comments in the heading should describe what the program does rather than how the code does it (you can read the code to see how it is done).

Any description of a method or comments about it should be in the Javadoc style and should be placed above the first line of the method.

Comments and blank lines that indicate the major sections of the subprogram are useful.

If (and only if) the meaning of a statement or group of statements is not clear from reading the code, brief comments may be included in the body of the program. In general these comments are not useful. If they merely state what is obvious from reading the code, they detract. If these comments are necessary, place them at the beginning of the block of code. This will reduce their disruption to the structure of the program. These embedded comments should generally use the double-slash (//) comment.

Variable and class names should be chosen to help describe their meaning. (a poorly chosen name that misleads the reader is worse than a nondescript name like x or a).

Variable names should be written in mixed case, but start with a lower-case letter. Even though Java regards '$' and '_' as letters, don't use them. For multiple word names begin the embedded words with an upper case letter, for example: taxRate, numberOfCars, etc.

Class names begin with an upper case letter. Method names begin with a lower case letter. We will not use prefixes to variables and methods to indicate data types as in the Visual Basic standard.

Organization of the source program

In order to make the class definitions easier to read and understand, the components should be included in a fixed order. Include the comment lines below to identify each set of items that is present (that is, if your program has no items in a category, omit the comment line). The items in all classes should be ordered as follows:

class constants
class variables
instance variables
class methods
constructor methods
instance methods
main method
inner classes

I have written a template which follows these guidelines: ClassTemplate.java

Within a method the local variables should be listed above the executable statements.

Software engineering standards

Each variable and class must have a meaningful name.

All float and double constants must have a decimal point with a digit on each side: 1.0, not 1.; 0.3, not .3.

Use double (instead of float) and int for all calculations. The only exception would be if memory was severely limited.

When possible, avoid mixed mode in arithmetic expressions. When possible, avoid mixed mode assignments.

Logical expressions that have more than one logical operator should have parentheses to indicate the operator priority.

Each variable should be declared on a separate line.

Each statement should be on a separate line.

Unnecessary code should be removed. This is particularly true when the code is inside a loop that will be executed numerous times. It is not necessary to assign the value zero to a variable or array element before it is assigned a value by another statement. Not sure about this one.

Access Modifiers

Java is a strongly-typed language, which means that all variables must be declared. Instance and class variables must explicitly declare whether they are private, package, protected, or public. For package access precede the variable definition with the comment: "/* package */". Public instance variables violate encapsulation. Provide access methods for instance variables and make the instance variables private.

Access modifiers should have the following order:

private|/*package*/| protected|public static abstract synchonized volatile final native

Constuctors

Always precede instance variables with this when assigning, this allows the arguments to have the same names as the instance variables.

Repetition

R1. Java has 3 repetition constructs: while, do while, and for. Note that java's while corresponds to Visual Basic's Do While whereas Java's do while corresponds to Visual Basic's Do Until (except the value of the boolean is reversed). For some repetition situations in a program, there is only one possible repetition construct that can be used. In most situations there is a choice. Each repetition construct was designed for a specific situation, therefore it is possible to develop standards that will dictate the appropriate repetition to use in most programming situations. The following give guidelines that will almost always dictate the appropriate choice:

R2. The while and do while constructs are called indefinite repetition because the number of times the loop is executed depends on calculations within the loop. Definite repetition is where the number of times through the loop can be known before the loop begins execution. The for construct in Java is very general and can be used for indefinite repetition; however, the standard limits the use of the for construct to definite repetition. When possible, use a definite repetition (that is, a for) rather than an indefinite construct.

R3. In choosing between the while and do while constructs, if the loop must be executed at least once then the do while is the appropriate choice because its selection clearly shows that the loop will be executed at least once. The while loop is thus used exclusively in situations where the loop may not be executed at all depending on the value of the logical expression.

R4. In for loops, the scope of the indexing variable must be only the loop itself:

for (int i = 0; i < n; i++) {
    // loop code here . . .
}

Notice that the for is definite iteration because we can see that the loop will be executed n times.

R5. The bracing for loops should be as above, with the left brace on the same line as the for statement and the closing brace on its own line, vertically aligned with the f.

Indentation and Braces

I1. Indentation is an extremely important element of readability. Java uses curly braces {} to delimit a block of statements. The default amount of indentation will be three (3) spaces.

Braces are used to delimit class definitions, method definitions, and statement blocks in loops and if statements. While there are several good styles of bracing, for consistency we will adopt the following convention:

The opening brace of a block is on the same line as the defining command, separated by a space. The closing brace is on its own line, vertically aligned with the statement that began it.

I2. Braces shall be used in all loops and if constructs. Unlike Java, the standard does not allow the braces to be omitted if the code has only one statement.

Examples of Braces and Indentation

Class definition:

public class Hello {
        // Code for the class Hello
}

Method definition:

   public int rating() {
        // Code for the method rating()
   }

For loop (while loop is similar):

      for (int i = 0; i < n; i++) {
          // code in the for loop
      }

Do while loop:

      do {
          // code in the do while loop
      } while (condition)

If conditional:

      if (test) {
           // code if test evaluates true
      }

If-else conditional:

      if (test) {
           // code if test evaluates true
      }
      else {
           // code if test evaluates false
      }

Nested loops follow the same pattern, as in the following example:

      while (condition) {
             // code
         if (test) {
             // code
         }
         else {
             // code
         }
             // code
      }