ICS Java Coding Standard

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-5 lines of code. 
  3. Be neat.

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 (exception only for those who use speech recognition software). 

Example 

private static float sumOfSquares = 0;

Counter
Example 

private static float Sum = 0;
private static float sumofsquares = 0;
private static float sum_of_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. For ICS 111, also add assignment, date, and bug information.

Example 

/** 
  * Prints a haiku.
  * @author         Suzuki, Susan
  * @assignment     ICS 111 Assignment 1 
  * @date           September 1, 2006
  * @bugs           None
  */
public class Haiku {
  //...
}

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.  (Omit @return and @exception, if the return value is void or there are no exceptions thrown.)

Example 

  /** 
    * Attempts to print a word. Indicates whether printing was possible.
    * @param word to print, must not contain spaces
    * @return true if printer is available, false otherwise 
    * @exception MyException if there are any spaces in the word 
    */ 
  public boolean printWord(String word) throws SpacesFoundException {
    //...
  }

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.
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

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

·  Lines of code should be kept short, generally less than 80 characters wide. 

·  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 package.

Other References

Websites

·        Code Conventions for the Java Programming Language by Sun Microsystems: http://java.sun.com/docs/codeconv/

·        How to Write Doc Comments for the Javadoc Tool by Sun Microsystems: http://java.sun.com/j2se/javadoc/writingdoccomments/index.html

 

Originally created by Dr. Philip Johnson (http://csdl.ics.hawaii.edu/~johnson/613f99/java-coding-standard.html)

Modified by William Albritton and Dr. Jan Stelovsky