ICS 111 Java Coding Standard

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.

Guidelines

·  Use descriptive names for all variables, function names, constants, and other identifiers. Use single letter identifiers only for the counters in loops and only if they denote indices, e. g. "i", "j", "k", or there where it is common in math, e.g., "x" and "y" for coordinates as well as "m" and "n" for number of rows and columns in a matrix. Do not use any abbreviations unless they are customary in the in the application's domain, e.g. "url" and "xml" are ok, but "btn" should be "button", "cmd" should be "command" and "args" or "argv" should be "arguments". Avoid being cute, e.g. by starting names with "my" -"myButton" doesn't describe the purpose of the button, but "quitButton" does.

·  Variable names start with lower case.

·  Multi-word identifiers are internally capitalized.

·  Do not use underscores to separate multi-word identifiers. Exceptions are: 1. package names, and 2. if you need to separate uppercase letters, e.g., "XML_Text". You can also use underscores if you use speech recognition software. 

Example

private float sumOfSquares = 0; 

Counter
Example

private float Sum = 0;

private float sumofsquares = 0;

private float sum_of_squares = 0;

private int w = 0;
private int h = 0;

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. (For ICS 111, also add assignment, date, and bug information.) Be precise but terse. Avoid starting the comment with "This class handles..." - obviously it is this class and not another one, the comment precedes the class declaration and every class handles something.

Example

/** Prints a haiku.

  * @author         Albritton, William

  * @assignment     ICS 111 Assignment 1

  * @date           September 1, 2005

  * @bugs           None */

public class Haiku {

  //...
}

Guidelines

Every method should be preceded with a descriptive comment using the "JavaDoc" notational convention. The comment should describe the purpose of the method, comment all its arguments, its return value, and all its exceptions using JavaDoc keywords.  (Omit @return if the return value is void.)

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 {

    //...

  }

Guidelines

Every public variable should be preceded with a comment using the "JavaDoc" notational convention. The comment should describe the purpose of the variable.

Example

  /** Toggles between Frame and NoFrame mode. */

  public boolean FrameMode = true;

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 but state in precise and terse English what is the purpose of the code. You should comment roughly every 3-5 lines of code.

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++) {

  //...

}

Guidelines

Use one blank line to separate each method within a class definition. Do not use any blank lines to separate logical sections of code within a method. When a new logical block starts, it's purpose needs to be documented on one or more separate comment lines and these lines separate it sufficiently from the preceding block.

Example

  public static void main(String[] arguments) {

    System.out.println ("Hello" + " " + "World"); 

  }

  public void gui() {

    // set up menus
    ...

    // position main window in the center of the screen
    ...

  }

Guidelines

·  Put a single space before every "{".

·  Put a single space after every ",".

·  Surround all operators and assignments, such as "+", "<" and "=" with a single spaces.

·  You can put a single space before "(" of a parameter list and before "[", or you can leave such spaces out - but you have to be consistent about it.

Example

  public void display (String label, int offset) {
    int length = offset [0] + offset [1] + label.length (); 

    System.out.println (index + "-th" + label + length);
  }

Counter
Example

  public void display(String label,int offsets) {
    int length=offset [0] + offset[1] + label.length(); 

    System.out.println (index +"-th"+label+length);
  }

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.

·  Statements blocks nested within if, else, for, while and do clauses are always enclosed in braces, even it there is only one statement in the block.

·  Don't ever use combination of two (or more!) assignments on a single line. (Note that "++" and "--" are assignments.)

·  If your statement becomes too long and you need to continue it on a new line, indent the subsequent lines by 4 spaces. You may consider to start the new lines with an operator to indicate that they belong to the preceding line.

Example

for (int i = 0; i < matrix.length; i = i + 1) {

  values.insertElementAt(new Float (matrix[i]), i);

  // Transmogrify is incremental and more efficient inside the loop.

  values.transmogrify();

}
if (x > 0) {
  System.out.println("positive x-coordinate");
} else if (x < 0) {
  System.out.println("x=" + x);
} else { // x=0
  System.out.println("on y axis");
} 
int sum = x += 2 + y; // x was incremented by y+2
System.out.println("this is an awfully long, long statement "
    + "that needs to be continued not on just one, but "
    + "several lines");

Counter
Examples

for (int i = 0; i < matrix.length; i = i + 1) 

{

  vals.insertElementAt(new Float (matrix[i]), i);

// Transmogrify is incremental and more efficient inside the loop.

    values.transmogrify();

  }
if (x > 0)
    System.out.println("positive x-coordinate");
else if (x < 0)
  System.out.println("x=" + x);
else // x=0
System.out.println("on y axis"); 
x += 2;
int sum = x + y; // x was incremented only by 2!
System.out.println("this is an awfully long, long statement " +
                   "that needs to be continued not on just " +
"one, but several lines");

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 classes, methods and variables.

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) {

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 package, i.e. there must be a package declaration in each file.

Websites

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

  Note that some of the Sun's conventions deviate from ours. Of course you have to follow our conventions until you start working for Sun.

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