General Comments on Documentation:
Once you have settled on a design of your algorithm, the best way to begin development of the software is to start with the internal documentation, a.k.a., comments. When you begin writing a method, before you write the first line of code, you should enter comments detailing in English or near-English the basic steps you intend to follow in the method. Then it is a matter of filling in the segments, one by one, and testing each segment thoroughly before moving on.

Then as new code is entered, if additional comments are warranted (for new variables being declared, a non-intuitive block of code has been developed, a loop is introduced, etc.) they should be entered at the same time.

To encourage students to adopt this disciplined and professional approach to software development, the following rule is established. If you want me to help you with your program, your code should be fully-commented. Moreover, it should contain enough System.out.println statements to reveal exactly which statement is causing the problem. There should also be println statements that reveal the contents of the primary structures in play at the time of the problem.

A simple, but effective, rule to follow is:

All programs submitted in this course must adhere to the following programming style requirements. Please follow them carefully to avoid point deductions on your programs.

Comments

1. Each class must be preceded by a header comment a sample of which is shown below:

      // Name:          Jane Smith, CPSC 212-1, Summer 2001, PROGRAM #1
      // Class:         SinglyLinkedList
      // Date Created:  January 17, 2000
      // Last Modified: January 20, 2000
      //
      // This class allows a user to instantiate an empty singly-linked  
      // list of objects.  The user may then add objects anywhere in the 
      // list, delete objects from the list, determine the number of 
      // elements in the list, determine whether a specific object is in
      // the list, and print the contents of the list.
      

2. All variables (instance variables, local variables) other than loop indices deserve a comment. For example:

      boolean  done;          // true when search of list is completed
      int      numberOfEggs;  // total number of eggs obtained from henhouse
      double   profit;        // difference between total revenue and total cost
      

   Note that the variables are all aligned and that all of the comments are aligned.

3. All major sections of code deserve a comment. This includes all but the simplest of loops and the most transparent of conditionals. For example:

      // find the minimum grade in the array of class grades
      minGrade = classGrade[0];
      for (int i=1; i < n; i++) {
         if (minGrade < classGrade[i])
            minGrade = classGrade[i];
      }  // end for*
   

   *Note the comment after the closing brace

      // assign a letter grade to a student using the standard 10-point scale
      if (grade < 60)
         letterGrade = "F";
      else if (grade < 70)
         letterGrade = "D";
      else if (grade < 80)
         letterGrade = "C";
      else if (grade < 90)
         letterGrade = "B";
      else 
         letterGrade = "A";
      

4. Short comments may be placed to the right of a statement. For example:

      if (name.equals(""))             // new customer; get name from file
         name = readLine(inputFile);
      System.out.println("Hello " + name + ". How can I help you today?");
      

Indentation

Bodies of (a) loops, (b) then and else blocks in conditionals, and (c) methods should be indented 3 spaces relative to the first statement.

Study each of the following sections of code carefully:

   //==============================================================

   for (int i=0; i< n; i++) {
      statement1;
      statement2;
      statement3;
   } // end for

   //==============================================================

   for (int i=0; i< n; i++) {
      statement1;
   
      for (int j=0; j< n; j++) {
         statement2;
         statement3;
         statement4;
      } // end j
   
      statement5;
   } // end i
   
   //==============================================================
   
   if (x > y) {
      if (y > z) {
         statement1;
         statement2;
   
         if (z == 0) {
            statement3;
            statement4;
         } // z==0
         else {
            statement5;
         } // z!=0
   
      } // y>z
   } // x>y
   
   else {
      statement6;
      statement7;
   } // x<=y
   
   //==============================================================
   
   public void removeSpaces(String line) {
   
      statement1;
      statement2;
      statement3;
   
   } // end removeSpaces

   //==============================================================
   

Package cucs, structure

   import cucs.*;
   import structure.*;

   /pub/faculty/turner/javalib/
   /pub/faculty/pargas/javalib/

Boundaries between class instance variables, constructors, and methods

To make it easier to distinguish one method from another in a class, insert comment boundaries. For example:

   class AppleFarm {
   
      // Instance variables
      . . .
      // =================================================================
   
      // Constructor(s)
      . . .
      // =================================================================
      
      // Methods
         public void seeds() {
            . . .
         } // end seeds
   
         //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   
         public void juice() {
            . . .
         } // end juice
   
         //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   
         public void core() {
            . . .
         } // end core
   
      // =================================================================
   
   } // end class AppleFarm 
   

Mnemonic variable names

   int          numberOfBalls;  // used by a bowler in a single game
   String       customerName;   // identifies each hotdog customer
   boolean      searchDone;     // true when search is complete
   

Boolean variables

   boolean     valueNotFound = true;// turns false when value found
   int         target = 50;         // value sought
   int         value;               // value provided by user
   BasicInputDataReader in = new BasicInputDataReader("input");

   while(valueNotFound) {
      value = in.readInt();
      if (value == target)
         valueNotFound = false;
   } // end while 
   

Additional Requirements

1. The single letter l should not be used as a variable name as it is too easily confused with the number 1.
   

                  (e.g. if (l == 1)  ...  )
           

2. Use Bailey's Assert class (Assert.pre(), Assert.post(), Assert(), and Assert.fail()) to specify pre, post, and general conditions for methods. Remember to include the line import structure.*; at the beginning of your class.

3. Use vertical spacing in addition to horizontal spacing. A blank line is a subtle way to seperate subtasks within a method without using an explicit comment, much the same way that an author tells the reader that she is moving on to another idea by starting a new paragraph.

4. Write conditionals in the form of constant == variable rather than variable == constant. For example:

                  if (value == 0) done = true; // can easy be miscoded as
                  if (value =  0) done = true;
           

   This is not a big issue in Java because a conditional expression must result in a boolean value. However, in C an C++, both of the above statements are legal.

   The following statement

                  if (0 = value) done = true;
            

   will generate a compile time error in Java, C, and C++.