Program Walkthrough: Program Style and Documentation

FirstApplet's complete source code is shown here.

/**
 *  File: FirstApplet.java
 *  Author: Java Java Java
 *  Description: This applet plays the click-me-not game with the user.
 */

import java.awt.*;
import java.applet.Applet;
import java.awt.event.*;

/*
 *  The FirstApplet class plays the click-me-not game with the user.
 *  @author Java Java Java
 */

public class FirstApplet extends Applet implements ActionListener
{
    private Button clickMe;                      // Declare the button

    /**
     *  The init() method initializes the applet.
     */
    public void init()
    {
        clickMe = new Button("Click Me Not!");   // Create the button
        clickMe.addActionListener(this);         // Activate the button
        add(clickMe);                            // Add it to the applet
    }  // init()

    /**
     *  The actionPerformed() method is called whenever the button is clicked.
     */
    public void actionPerformed (ActionEvent e)
    {
        if (clickMe.getLabel().equals("Click Me!"))
            clickMe.setLabel("Click Me Not!");
        else
            clickMe.setLabel("Click Me!");
    }  // actionPerformed()
}  // End of FirstApplet

The program begins with a comment block, which presents important information about the program, including the name of the file that contains it, the name of the author, and a brief description of what the program does.

Java Language Rule: Comments. A multiline comment begins with ``/*'' and ends with ``*/'' and may extend over several lines. It is ignored by the compiler. A multiline comment that begins with ``/**'' and ends with ``*/'' is called a documentation comment. These kinds of comments can be processed by special software provided by Java that will automatically generate documentation for the class.

Programming Tip: Use of Comments. A well-written program should begin with a comment block that provides the name of the program, its author, and a description of what the program does.

In addition to the comment block at the beginning of FirstApplet and several other comment blocks in the program, there are also several single-line comments used to clarify the code. Commenting your code in this way is an important part of program development. Appendix A lays out the style and documentation guidelines that are followed in this book. In subsequent laboratory projects, as our programs become more sophisticated, we will introduce additional documentation requirements.

Students invariably hate putting comments in their programs. After all, it seems somewhat anticlimactic, having to go back and document your program after you have finished designing, writing, and testing it. The way to avoid the sense of anticlimax is to ``document as you go'' rather than leaving it to the end. In many cases, your design document can serve as the basis for the comments in your program. One of the main reasons for commenting code is so that you, or someone else, will be able to understand the code the next time you have to modify it. Students who go on to be professional programmers often write back with reports that they now understand how important program documentation is. As one of my former students told me,

Lanning's Limerick

All hard-headed coders say ''Phooey,
    Putting comments in code is just hooey!''
    But when they are asked,
    To reread what they hacked,
    They discover their programs are screwy.