CS 180 Java Programming Standards

PURPOSE

FILE NAMES AND JAVA COMPILER

1. The program name, your name, and recitation section.
2. A brief description of the program that describes the method or algorithm used to obtain the solution, the major data structures (if any) in the program, and other general comments including extra features.
3. The date the program was completed.

The format to be used is as follows:

/**
 * Program Name
 * brief description of the program
 *
 * @author your name
 *
 * @recitation section number and recitation instructor's name
 *
 * @date date of completion
 *
 */

The following is an example of an introductory comment block that follows the format above:

/**
 * Project 1 -- Video Calculator
 * This program inputs the total number of minutes,
 * the number of minutes for commercials, and the
 * number of minutes for episodes.  The program
 * computes the total number of minutes for videos,
 * the number of videos, and the number of seconds
 * left over.
 *
 * @author Elwood Blues
 *
 * @recitation 03 (Andy Scharlott)
 *
 * @date September 14, 2005
 *
 */

DECLARATIONS

1. You should use mnemonic names for all identifiers. These are names that have meaning in the problem. The names should suggest the use of the identifier.

2. Variable identifiers should be in all lower-case letters, except for capital letters used to delimit multiple words in a variable identifier. For example, shipRates, idEntry, numItems, and minScoreRequired.

3. Constant values used in your program will be given in final declarations. Constant identifiers should always appear in all-capital letters; underscore characters delimit multiple words. For example:
   

   final float BASE = 2.0;       // divisor to obtain base 2
   final char HYPHEN = '-';      // signals word continued on next line
   final int NAME_LENGTH = 20;   // names can be 20 characters
   

4. Classes should begin with a capital letter, and multiple words should be indicated by additional capital letters (for example, Date, VehicleNumber, SoftwareEngineer, BankAccount).

5. Methods should begin with a lowercase letter, and have any multiple words indicated by capital letters (for example, isValidNumber(), area(), setWidth(), etc). Note: Constructors are methods which cannot follow this convention, because their names must exactly match the class name.

6. Each identifier declaration (including method declarations) must be accompanied by a comment that explains its use.

7. Avoid declaring globally-visible variables. Globally-visible constants, enumerated types, classes, and file names are okay, but do not use global variables unless the project assignment specifically tells you to do so.

1. Each constant and variable declaration should be on a separate line that includes a comment that explains what each is. For example:
   

   float volts;                     // voltage in the circuit 
   int amps;                        // amperage in the circuit 
   char circuitName[NAME_LENGTH];  // name of the circuit 
   

2. Each statement should be on a line by itself. For example, instead of
   

   left = nextLeft;    right = nextRight;
   

   use

   left  = nextLeft;     // move to the left
   right = nextRight;    // move to the right
   

3. Each method should be identified by a comment block describing its purpose, parameter(s), and the method(s) it calls. The format to be used is as follows:

   /**
    * calculates and returns the charge for shipping cargo
    * between two planets.
    *
    * @param distance distance in miles between two planets
    * @param weight weight in pounds of item being shipped
    * @return A double representing the cost to ship the item in space
    */
   public double findSpaceCost(long distance, float weight)
   {
     // implement here
   }
   

4. Comments should be set apart from the code by at least two spaces, making it easy to see where the code ends and comment begins.

   
   

   FORMATTING AND COMMENTING OF STATEMENTS

   Alignment and indentation of lines of Java statements add much to the readability of programs. The following guidelines are general so that you may develop your own programming style. Use indentation and blank lines as you see fit to increase the readability of your programs. Use whitespace (blank lines and spaces on lines) liberally! Use parentheses liberally!!

   The body of a control structure, such as an if, a switch, a while, a do, or a for statement, should be indented. The following examples illustrate the only formatting style that is to be used in CS180. Each level of indenting is 4 spaces. (All of the below examples should have 4 spaces for indentation, but not all browsers display it correctly.)

   if statement
   
   if (expression)
   {
       statements
   }
   
   if-else statement
   
   if (expression)
   {
       statements
   }
   else
   {
       statements
   }
       
   
   switch statement
   
   switch (selector variable) 
   {
       case case-1-value: 
           case 1 statements;
           break;
       case case-2-value: 
           case 2 statements;
           break;
       ...
       case case-n-value: 
           case n statements;
           break;
       default: 
           default statements;
           break;
   }
       
   
   while statement
   
   while (expression)
   {
       statements
   }
   
   
   do-while statement
   
   do
   {
       statements
   }
   while (expression);
   
   
   for statement
   
   for (initialization; condition; increment)
   {
       statements
   }
   
   

   
   

   PROGRAM DESIGN

   1. Use stepwise refinement. The programming assignments given are ones that can be solved in a step-by-step manner. The method of solution used in your program should exhibit this kind of structure.

   2. Modularize your program. When a problem solution readily splits into distinct tasks, your program should handle each task in a separate function and in a straightforward manner.

   3. Make your program efficient. Your algorithm should be direct and not unnecessarily complicated. Proper use of data structures will often simplify an algorithm.

   4. Use parameters appropriately. All variables used in a method should either be declared as parameters or be declared locally within the method.

   
   

   OUTPUT

   1. All input values should be echoed in a readable manner unless otherwise indicated.

   2. The program output should be readable and clearly labelled. Headings should be used when appropriate.

   3. Finally, of course, your program should produce correct results!

   ---