CSC 161 Documentation and Style Standards

This document spells out the standards you should adhere to while documenting your CSC 161 programs. While these are reasonable standards, you should be aware that other instructors, or your employer after you graduate, may have different documentation standards or conventions. Always use the standards established by your instructor or employer.

This document may be amended, revised, or added to as the term progresses. I will alert you whenever there is an addition. You are responsible to apply the latest version of this document to programs that you hand in.

  1. The purpose of documentation is to assist those that read the program. Your comments should be informative and provide information that is not otherwise obvious. Comments that restate the obvious just get in the way:
    1. A variable may not need to be commented if its use is obvious from its name.
    2. There is no need to provide a comment on the ActionEvent parameter of an actionPerformed method if the method does not use the parameter, or to provide comments of the command line arguments of a main method that does not use those arguments.
    3. A loop control variable in a very short for loop usually does not need a comment, nor does its name need to be long. For example, just use k insted of loopControlVariable.
  2. The author and purpose of the program, file, or class, should be clearly identified.
  3. /**
     * 
     * @author gcmuganda
     * This program illustrates how to use a timer to make the background color
     * of a component cycle through a number of colors. The component will display
     * a color and hold it for one second before moving on to the next color.
     * A start button will start the color animation, and a stop button will
     * pause it.
     *
     * ---Program description serves as the documentation for the main class
     */
    
    Here is another example:
    
    /**
     * An object of this class is responsible for cycling the background
     * color of a component through an array of Colors. The Component and
     * tne array of colors are passed to constructor of the object, and stored
     * for later use by its other methods. A actionPerformed method will set
     * a new color for the component each time it is called.
     * @author gcmuganda
     */
    class ColorCycleTimerListener implements ActionListener
    {
        private Component comp;      // Component whose color to set
        private Color [] colors;     // Colors to set the component to.
        private int currentColorPos; // Array position of color to use on comp
    
    
  4. Every method should have a comment that explains what it does in terms of the parameters it takes. If the method returns a result, the comment should explain how the result is related to the parameters. Here is an example.
  5.    
        /**
         * Constructor
         * @param comp  A reference to the component whose color is to be set.
         * @param colors  The array of colors to use when setting color of comp.
         */
        public ColorCycleTimerListener(Component comp, Color[] colors)
        {
           // Save the parameters in class fields
           this.comp = comp;
           this.colors = colors;
        }
    
  6. Vertically align braces for a block. Write
  7.  
        if (expr)
        {
            
        }
      
    rather than
        if (expr){
        
        }
      
    Other instructors might prefer or might not mind the second form (which is also standard).
  8. Avoid overly long lines of code: long lines are broken up hapzardly by the printer when the progrm is printed, or sometimes, they are cut off. As a rule, you should break a line before you cross the red line in Netbeans.
  9. Use indentation to enhance readability, but avoid using tabs to indent your program code. Use two or three spaces instead. Tabs cause you to quickly run off the edge of the page with high level of nesting.
  10. Use class, loop, and program invariants where appropriate. Likewise, use method preconditions and postconditions. These will be explained later in the course.
Here is a complete example of a well-documented program with good style:


package colorswichontimer;

import java.awt.Color;
import java.awt.Component;
import java.awt.FlowLayout;
import java.awt.event.ActionEvent;
import java.awt.event.ActionListener;
import javax.swing.JButton;
import javax.swing.JFrame;
import javax.swing.Timer;

/**
 * ---Need author and description of the program
 * @author gcmuganda
 * This program illustrates how to use a timer to make the background color
 * of a component cycle through a number of colors. The component will display
 * a color and hold it for one second before moving on to the next color.
 * A start button will start the color animation, and a stop button will
 * pause it.
 *
 * ---Program description serves as the documentation for the main class
 */
public class Main
{
    /**
     * Creates a frame to hold the buttons for starting and stopping
     * the animation, and sets up the listeners to make the program 
     * work.
     * @param args
     */
    public static void main(String[] args)
    {
       // Create the JFame
       JFrame myFrame = new JFrame("Color Cycle Madness");
       myFrame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
       myFrame.setLayout(new FlowLayout());

       // Create the listener and timer to control the animation
       Color[] colors = {Color.WHITE, Color.YELLOW, Color.MAGENTA, Color.PINK};
       Component cPane = myFrame.getContentPane(); // Component color to change
       ActionListener colorCyclerListener =
               new ColorCycleTimerListener(cPane, colors);
       Timer timer = new Timer(1000, colorCyclerListener);

       // Now create the buttons and associated listener
       JButton startButton = new JButton("Start");
       JButton stopButton = new JButton("Stop");
       ActionListener buttonListener = new StartStopButtonListener(timer);
       startButton.addActionListener(buttonListener);
       stopButton.addActionListener(buttonListener);

       // Add the buttons to the frame
       myFrame.add(startButton);
       myFrame.add(stopButton);
       myFrame.pack();

       // Make frame visible
       myFrame.setVisible(true);

       // Start the timer
       timer.start();
    }
}


/**
 * An object of this class is responsible for cycling the background
 * color of a component through an array of Colors. The Component and
 * tne array of colors are passed to constructor of the object, and stored
 * for later use by its other methods. A actionPerformed method will set
 * a new color for the component each time it is called.
 * @author gcmuganda
 */
class ColorCycleTimerListener implements ActionListener
{
    private Component comp;      // Component whose color to set
    private Color [] colors;     // Colors to set the component to.
    private int currentColorPos; // Array position of color to use on comp

    /**
     * Sets background color of comp to the color at currentColorPos
     * and advances currentColorPos
     * @param e
     */
    public void actionPerformed(ActionEvent e)
    {
       comp.setBackground(colors[currentColorPos]);
       currentColorPos  = (currentColorPos+1) % colors.length;
    }
    /**
     * Constructor
     * @param comp  A reference to the component whose color is to be set.
     * @param colors  The array of colors to use when setting color of comp.
     */
    public ColorCycleTimerListener(Component comp, Color[] colors)
    {
       // Save the parameters in class fields
       this.comp = comp;
       this.colors = colors;
    }
}

/**
 * This class implements the listener to the Start and Stop buttons
 * to start and pause the color cycling animation. The class is
 * passed a reference to the timer tnat  controls the color animation
 *
 * @author gcmuganda
 */
class StartStopButtonListener implements ActionListener
{
    private Timer timer;
    /**
     * Constructor. Creates and starts the timer.
     */
    public StartStopButtonListener(Timer timer)
    {
      this.timer = timer;
    }
    /**
     * actionPerformed responds to start and stop buttons
     * by restarting / stopping the timer
     * @param e
     */
    public void actionPerformed(ActionEvent e)
    {
        if (e.getActionCommand().equalsIgnoreCase("Start"))
            timer.restart();
        if (e.getActionCommand().equalsIgnoreCase("Stop"))
            timer.stop();
    }
}