Style Principles for CS 235

Follow these rules for style and documentation in all programs turned in for a grade. You will be penalized for violations. The rules refer to concepts covered at various points throughout the semester, so don't worry if there are references to things you don't recognize. Follow all the rules that apply to what has been covered. See below for an example.

1. Begin each file with a block comment containing:
   • The name of the file.
   • A blank line.
   • A short paragraph description of the program or component.
   • A blank line.
   • Your name with an author tag.
   • "Wheaton College, CS 235, Fall 2009"
   • The date; if there are major revisions, mention those.
2. Use the tabbing provided by XEmacs.
3. Put opening curly braces on the same line as the method signature, loop header, etc; except for one-liners, do not put other code on the same line as curly braces.
4. Each local variable should have a line comment above or next to it containing a one-sentence description of its use.
5. Any complicated statement should be explained in a line comment above it or next to it.
6. The names of classes should be capitalized; all other identifiers should begin with a lower case letter; identifiers composed from several words should have the subsequent words capitalized; all other letters should be lowercase.
7. Every class, method, and instance variable should be either public or private; you must have a very good reason for an instance variable to be public.
8. Each method should be be preceded by a block comment containing:
   • A one-sentence description of the functionality of the method in the imperative.
   • Except for trivial methods, a few sentences describing the algorithm.
   • Any preconditions, headed by "PRECONDITION:".
   • Any postconditions, headed by "POSTCONDITION:".
   • A param tag and description for each parameter.
   • Except for void methods, a return tag with a description of what's returned.
   • An exception tag for any exceptions you know of.
9. Each instance variable should have a block comment containing a one-sentence description of its use.
10. Any package importation should have a line comment above it or next to it saying why it is imported.

/**
 * Example.java
 * 
 * This class computes the running average of a series of integers as
 * they are fed to it.
 * 
 * @author Benjamin Franklin
 * Wheaton College, CS 235, Spring 2005
 * Assignment 19
 * Jan 3, 2005
 */

import java.util.*;   // For Stack

public class Example {

    /**
     * Running average of the numbers entered.
     */
    private double average;

    /**
     * The number of entries.
     */
    private int number;

    /**
     * A record of the numbers entered in first-in-last-out order.
     */
    private Stack inputs;

    /**
     * Constructor. 
     * Sets the average to "not a number" since there is not average of zero numbers.
     * The number of entries is default, and the input record is an new, empty stack.
     */
    public Example() {
	average = Double.NaN;
	number = 0;
	inputs = new Stack();
    }

    /**
     * Enter a new number to be averaged.
     * If there is no average (because of no entries), the entry is the new average.
     * Otherwise, calculate the new average by getting the old total (multiplying
     * the average by the number of entries), adding the entry, and dividing by
     * the new number of entries (old number plus one). Increment the
     * number of entries and record the new entry.
     * POSTCONDITION: The average has been adjusted for the new entry
     * and the entry has been pushed on the record stack.
     * @param entry The new number to be worked into the average.
     */
    public void addNextEntry(int entry) {
	if (average == Double.NaN) 
	    average = entry;  
	else {                            
	    // The total of all previous entries.
	    double oldSum = average * number;  
	    average = (oldSum + entry) / (number + 1);
	number++;
	inputs.push(new Integer(entry));  // Can't store an int in a Stack; need wrapper
    }

    /**
     * Retrieve the average of the entries.
     * @return The average.
     */
    public double getAverage() { return average; }

    /**
     * Undo the most recently entered number included in the average.
     * Remove the top entry in the input record. If that's the last one left
     * (first one entered), revert to the original state. Otherwise,
     * recalculated the average by finding the sum (average times old number of entries)
     * minus popped entry, divided by the newly adjusted number.
     * PRECONDITION: The inputs stack is not empty.
     * POSTCONDITION: An entry is removed from the inputs stack and the
     * average  and number are adjusted accordingly.
     * @exception RuntimeException if the inputs stack is empty to begin with.
     * @return The old, removed entry.
     */
    public int undo() {
	if (inputs.isEmpty()) 
	    throw new RuntimeException("Can't undo");
	// The most recent entry
	int entry = ((Integer) inputs.pop()).intValue();  // Stored as Object; need int
	if (inputs.isEmpty()) {
	    average = Double.NaN;
	    number--;
	}
	else 
	    average = ((average * number) - entry)/(--number);
	return entry;
    }
}