Introduction

One of our goals is to write programs that are easily understood by the reader especially the other team members. This becomes particularly important when programs get large. For example, suppose you find a reference to an unfamiliar identifier in a program. You may have to look through many screens of code to find the declaration of that identifier to find out that it is the name of a class. A much better alternative is to use identifier names that tell you something about the name. Ideally, you should be able to look at an identifier and determine whether it is the name of a function, object or class. This document suggests naming guidelines that are based on ones used in industry by companies that produces Java Application Programming Interfaces (APIs) or class libraries. The guidelines are based on the one for C++ in CSCI 204 and Java coding standards at SUN and other companies.

To realize the benefits of having a coding standard for a team, every programmer on the team must abide by it.

Java Source File Organization

A Java source file contains the following sections:

• beginning comments
• package import statements
• class definitions
• ending comment

The file Template.java can be used as a template for creating Java source files. Note that the following uses comments which can be read by SUN's javadoc documentation tool. See Appendix G on page 1271 in Java How to Program by Deitel and Deitel, third edition. The "@" characters are javadoc tags. Documentation comments begin with "/**".

/*
 * File:        Template.java
 * Description: Purpose of the program
 */
import javax.swing.*;

/**
 * Comment describing class
 * @author  Sally Brown
 * @version 0.1
 * Date created: October 15, 2000
 * Date updated: October 20, 2000
 */

public class Template {

  /* Class data members: public, protected then private
   */

  /**
   * mAge is age of employee; mAge > 0
   */
  public int mAge;

  /**
   * Method with no parameters and no return value
   */
  public void Display(){

  }

  /**
   * Method with  parameters and return value
   *
   * @param parameter1 description
   * @param parameter2 description
   * @return value
   */
  public int Add(int inX, int inY) {
     int z;
     z = inX + inY;
     return z;
  }
}
/*
 * End Template.java
 */

Spacing and Comments

• Use blank lines to separate logical sections of your program.

• Use spaces around = and around operators and after commas and semi-colons. For example:

     String strHeight;
     String strWeight;
     double potWeight;  // potential weight of the individual
     double height;     // height of individual in feet
     double weight;     // weight of individual of pounds
  
     strHeight = JOptionPane.showInputDialog( "Enter your height in feet" );
     height = Double.parseDouble( strHeight );
  
     strWeight = JOptionPane.showInputDialog( "Enter your weight in pounds" );
     weight = Double.parseDouble( strWeight );
  
     potWeight = 3.0 + height * 2.7; 
  

• Use comments to describe major sections of programming or where something needs to be clarified.

• Indent if, for, while and try constructs as shown:

      if ( weight > potWeight ) {
          System.out.println( "Too Big!"); 
      } 
      else {
          System.out.println( "OK.");
      }
  
      for ( i = 1; i <= n; i++ )
      {
          s = s + 1; 
      }
  
      while ( i > 0 )
      {
          System.out.println( "Dont't Panic!");
          i = i - 1;
      }
   
      try{
          // statements
      }
      catch ( ExceptionClass1 e) {
  
      }
      catch ( ExceptionClass1 e) {
   
      }
  
  

  Use the automatic indenting feature of emacs.

• All functions and methods should have a series of comments which state the intent and the pre and post conditions. A pre-condition is a sentence or two which states what must be true before the function is called. The post-condition states what is true after the function is called.

      
    /**
     * Sum method finds sum of integers from 1 to inN
     *
     * @param inN 
     * @return the sum
     *
     * Intent: To sum the positive integers from 1 to inN. 
     * Pre: The object inN must have a value and inN > 0. 
     * Post: The function returns the sum from 1 to inN.
     */
    int Sum (int inN)
       { 
          return inN + Sum( inN - 1 );
       } 
  

Class Names

Any class that you define should be a noun and begin with an uppercase C. This helps you to distinguish them from the ones in a class library. For example, a class defining rational numbers might be called CRational.

Object Names

Object (variable) names begin with a lowercase letter and use embedded uppercase letters for word breaks. Do not use underscores in object names. The first letters of the object name are the prefix, reflecting how the object is used:

   Prefix  Meaning                    Example
     m     data member of a class     mFrameSize
     s     static data member         sClickCount 
     in    input parameter            inCommand 
     out   output parameter           outMenu
     io    input/output parameter     ioParam 
     the   a local copy of an object  thePane 

Function Names

Function names should be verbs and begin with an uppercase letter and use embedded uppercase letters for word breaks. Here are some examples:

   ReadCharacter(); 
   RefreshScreen();

Constants

Constants should contain an underscore, which is also a word break. The under-score is never the first or last character. Embedded capitals are used for other word breaks.

   final int Bow_Wow = 1;