Java Coding Standard

Philip Johnson

Last modified: Sat Sep 11 15:08:01 HST 1999

Overview

This document presents one high quality approach to the layout and presentation of java source code. It generally conforms to the style used in the SUN java sources.

Identifier Naming and Capitalization

Guidelines
  • Use descriptive names for all variables, function names, constants, and other identifiers. Use single letter identifiers only for the counter in loops.
  • Variable names start with lower case.
  • Multi-word identifiers are internally capitalized.
  • Do not use hyphens or underscores to separate multi-word identifiers.
    • Example 
    private static float sumDiffSquares = 0;
    Counter
    Example 
    private static float Sum = 0;
private static float sumdiffsquares = 0;
private static float sum_diff_squares = 0;
private static float x = 0;

    Comments: Classes

    Guidelines Every class should be preceded with a descriptive comment using the "JavaDoc" notational convention. The comment should name the class, describe its purpose, and name the author and (optionally) the version using JavaDoc keywords.
    Example 
    /**
 * Hello1 --- A simple program to print out "Hello World".
 * @author         Philip Johnson
 * @version        $Id: Hello1.java,v 1.3 1998/03/23 21:23:39 johnson Exp $
 */
public class Hello1 {
 :
}

    Comments: Methods

    Guidelines Every method should be preceded with a descriptive comment using the "JavaDoc" notational convention. The comment should name the method, describe its purpose, comment all arguments, the return value, and any exceptions using JavaDoc keywords.
    Example 
      /**
   * main --- Prints out "Hello World" and the command line arguments.
   * @param arg A string array containing the command line arguments.
   * @return No return value.
   * @exception Exception If the file is not found or other error.
   */ 
  public static void main (String[] arg) throws Exception {
   :
  }

    Comments: Public variables

    Guidelines Every public variable should be preceded with a descriptive comment using the "JavaDoc" notational convention. The comment should describe the purpose for the public variable.
    Example 
      /** Toggles between Frame and NoFrame mode. */
  public boolean FrameMode = True;

    Comments: In-line

    Guidelines In-line comments should be used to explain complicated sections of code, such as loops. Use the // comment delimiter for in-line comments. Do not comment generally known features of the java language.
    Example 
    // Do a 3D transmogrification on the matrix in args.
for (int i=0; i < args.length; i++) {
  for (int j=0; j < args.length; j++) {
    for (int k=0; k < args.length; k++) {
      vals.transmogrify(args[i], args[j], args[k]);
    Counter
    Example 
    // the variable "i" loops from 0 to the length of args.
for (int i=0; i < args.length; i++) {
 :
}

    Spacing: Between lines

    Guidelines Use two blank lines to separate each method within a class definition. Use one blank line to separate logical sections of code within a method.
    Example 
      public static void main(String[] arg) {
    System.out.println ("Hello" + " " + "World"); 
  }


  public void foo() {
  :
  }

    Spacing: Within lines

    Guidelines
  • Put a single space before every "{".
  • Separate all operators such as "+" with a single space.
    • 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
  • Indent two spaces when beginning a new block.
  • Open braces (i.e. "{") do not start a new line.
  • Close braces (i.e. "}") do start a new line, and are indented with the code they close.
  • Comments line up with the block they comment.
    • 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
  • Classes begin with a capital letter.
  • Packages are all lower case.
  • Methods begin with a lower case letter.
  • Multi-word identifiers are internally capitalized in methods.
    • Examples 
    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
  • Each public class is contained in a separate file.
  • Each file has the name of the public class contained within it.
  • Avoid the use of the default class.

    • Version Control

    Guidelines It is useful, but optional to include automated time/date stamping of creation and modification dates. Emacs and other decent editors will do this for free.
    Example 
    //                          -*- Mode: Jde -*- 
// meanStd.java -- 
// Author          : Philip Johnson
// Created On      : Tue Dec 26 11:02:36 1995
// Last Modified By: Philip Johnson
// Last Modified On: Thu Jan  4 16:02:01 1996
// RCS: $Id$
//
//   Copyright (C) 1995 Philip Johnson
//
//