Java Coding Standard

Explanation

When you write the comments this way, you can automatically generate web pages that describe your classes and methods. If you look at the Java API, you can see what these web pages look like. This style of writing comments is called "javadoc" (for "java documentation"). Javadoc is the industry standard for Java program comments.

When you use Javadocs in your program, you can create your own webpages from the program, similar to the Java API. For example, this example program ArraysAndMethods.java generates the following ArraysAndMethods API (Application Program Interface).

To create a webpage from the Javadocs in your program, open your program in jGRASP, click "File", then click "Generate Documentation".

You should see any Javadoc errors in the "Compile Messages" window at the bottom. Then, a browser should automatically open with a webpage describing your program!

The Java Coding Standard is based on the Java language coding conventions. For more details on the Java language coding conventions, see Java Code Conventions - Oracle

Basic Coding Rules to Follow

  1. Use descriptive and appropriate names for all identifiers (variables, method names, class names, constants, etc.).
  2. Comment every 3-7 lines of code.
  3. Be neat.

Identifier Naming and Capitalization

Guidelines

Example

float sumOfSquares = 0;
final int DAYS_IN_YEAR = 365; //Use UPPER_CASE for constants (final variables)

Counter Example

float Sum = 0;
float sumofsquares = 0;
float sum_of_squares = 0;
float x = 0;

Comments: Classes

Guidelines

Example

/**
 * Stores the first, middle, and last names for a president. 
 */
class President {
   //code...
}

Comments: Methods

Guidelines

Example

/**
 * Prints a word, prints a number, and returns integer 1
 *
 * @param word any string of Class String
 * @param number an integer of any value
 * @return the integer 1 
 * @exception MyException if the word starts with the letter 'z'
 * @exception YourException if the number is a zero(0)
 */ 
public static int method1(String word, Integer number) throws MyException, YourException{
  //code...
  if(word.charAt(0) == 'z'){
    //thrown, but not caught in method, so put in JavaDocs above 
    throw new MyException();
  }
  if(number == 0){
    //thrown, but not caught in method, so put in JavaDocs above
    throw new YourException();
  }
  try{
    int x = 5 / 0;
  }
  catch(ArithmeticException exception){
    System.out.println("ERROR: Division by zero! " + exception); 
  }
  
  return 1; 
}

Comments: Public variables

Guidelines

Example

/** Toggles between frame and no frame mode. */
public boolean frameMode = true;

Comments: In-line

Guidelines

Example

// Do a 3D transmogrification on the matrix.
for (int i = 0; i < matrix.length; i++) {
  for (int j = 0; j < matrix.length; j++) {
    for (int k = 0; k < matrix.length; k++) {
      values.transmogrify(matrix[i],matrix[j],matrix[k]);
    }
  }
}

Counter Example

i++; // increments i
// the variable "i" loops from 0 to the length of matrix
for (int i = 0; i < matrix.length; i++) {
  // ...
}

Spacing: Between lines

Guidelines

Example

public static void main(String[] arg) {
    System.out.println("Hello" + " " + "World");
  }

  public void foo() {
    // ...
  }

Spacing: Within lines

Guidelines

Example

public static void main(String[] arg) {
    System.out.println("Hello" + " " + "World");
  }

Counter Example

public static void main(String[] arg){
    System.out.println("Hello"+" "+"World");
  }

Indentation

Guidelines

Example

for (int i=0; i < args.length; i = i + 1) {
  vals.insertElementAt(new Float (args[i]), i);
  // Transmogrify is incremental and more efficient inside the loop.
  vals.transmogrify();
}

Counter Example

for (int i=0; i < args.length; i = i + 1)
{
  vals.insertElementAt(new Float (args[i]), i);
// Transmogrify is incremental and more efficient inside the loop.
  vals.transmogrify();
  }

Class, Package, and Method Naming and Capitalization

Guidelines

Example

package foo.bar.baz;
public class MeanStandardDeviation
private Vector getNewVector(Vector oldVector) {

Counter Example

package Foo.Bar.Baz;
public class Meanstandarddeviation
private Vector GetNewVector(Vector oldVector) {

Program Modules

Guidelines

Other References

Website


Click to validate the HTML code

Click to validate the CSS code