Documenting your program's code

Recall that a comment is an area in your program that is deliberately ignored by the compiler. Programmers put comments in their program's code to help themselves and others understand their code.

This document provides a brief explanation of:

• Why you should document your program's code
• Why you should use the disciplined design process called Javadoc
• How to write Javadoc comments

Why should I document my program's code?

For small programs that have a very short lifetime and a single author, perhaps the code itself is enough. But software engineers almost always are working on:

• large programs
• that are written and then modified over a period of months or years
• by a team of authors.

For example, much of the Unix operating system that is still popular today was originally written almost 30 years ago by a team of software engineers at Bell Labs. With code like that, it is critical to document the code, so that software engineers who work on it later can modify it appropriately.

To help you become a successful software engineer, we will require that you document the code you write for this course.

Why should I use a disciplined design process? Why use Javadoc?

Software engineers have found that by using disciplined design methods, they increase their productivity on large, dynamic, team-written software. You will learn a variety of disciplined design methods here at Rose-Hulman and in your subsequent career.

Some such disciplined design methods will be better than others. Some will fit your personality better than others. But we want to make the point, right from the start, that you must use disciplined design methods to be a successful software engineer.

Thus, we will require that you use a disciplined design method called Javadoc for documenting your Java code.

Javadoc allows you to put comments in your code using a special notation (details shortly) and then automatically convert those comments to a form that humans can read more easily than your code. For example, your Javadoc comments will be automatically converted to an HTML document.

In fact, these HTML documents that you generate will use a very standard form --- the very same form that JDK uses for its own documentation. (You saw such documentation when you used JDK Help in an earlier part of JavaEyes.) So by using Javadoc, you are learning a standard, disciplined design method, and also learning how to read and use the thousands of existing Java methods that you can use.

How do I write Javadoc comments?

The documentation to be processed by Javadoc is placed in what are called doc comments.

General form of a doc comment

A doc comment is made up of two parts -- a description followed by zero or more tags (see below), with a blank line (containing a single asterisk "*") between these two sections:

    /** 
     * This is the description part of a doc comment.
     *
     * @tag    Comment for the tag
     */

• The first line is indented to line up with the statement below the comment, and starts with the begin-comment symbol /**
  • An ordinary comment begins with /*
  • A doc comment begins with /**
  • It is the second asterisk that makes this comment into a doc comment

• Subsequent lines start with an asterisk *. They are indented an additional space so the asterisks line up. A space separates the asterisk from the descriptive text or tag that follows it.

• Insert a blank comment line between the description and the list of tags, as shown.

• The last line begins with the end-comment symbol */, indented so the asterisks line up. Note that the end-comment symbol contains only a single asterisk (*).

Rules for doc comments

To make Javadoc work correctly, you must follow certain rules in your doc comments. In this course, we will adhere to a simplified subset of the Javadoc rules, as described below. The full set of rules are available from Sun's How to Write Doc Comments for Javadoc page at Sun's Javadoc Tool Home Page and much of what follows is taken verbatim from that source.

Obey the following rules whenever you document your code. Some of the rules may seem cryptic at this point, but when you need them you will understand them.

---

Rule #1 (who has a doc comment):

• Every declaration of a non-private interface, class, constructor, method or field must have a doc comment immediately before it.
• Doc comments should appear nowhere else.

---

Rule #2 (first sentence):
The first sentence of each doc comment should be a summary sentence, containing a concise but complete description of the declared entity (class, method, whatever) being documented. This sentence must end with a period followed by a newline. However, this sentence may span multiple lines and may be followed by additional sentences. For example:

/**
 * The JavaEyes class is a Java-based implementation of the
 * familiar "xeyes" program, available on many Unix-based systems.
 * Each JavaEyes object is a pair of "eyes" whose eyeballs
 * follow the movement of the mouse.
 */

---

Rule #3 (required tags):
There are special tags that can be used in Javadoc to indicate that a specific type of information is about to be given. There are many tags, but we require only these:

• @author   name
  Each class or interface must have an @author tag that indicates the author(s) of the class or interface. For example:

  /**
   * The JavaEyes class is a Java-based implementation of the
   * familiar "xeyes" program, available on many Unix-based systems.
   * Each JavaEyes object is a pair of "eyes" whose eyeballs
   * follow the movement of the mouse.
   *
   * @author Anonymous students at MIT and elsewhere.
   *         Modified by Claude Anderson and David Mutchler.
   */
  

• @param   parameter-name   parameter-description
  Each method or constructor that has one or more parameters must have an @param tag -- one tag per parameter. The description of the parameter can span multiple lines. For example:

    /**
     * Builds a JavaEyes object,
     * and starts a Thread to animate the eyes in 
     * response to the mouseMoved event. 
     *
     * @param bgColor  the background color of the JavaEyes window
                       (for example, Color.white)
     * @param fgColor  the foreground color of the JavaEyes window
                       (for example, Color.black)
     */
  

• @return   return-description
  Each method whose return type is not void must have an @return tag that describes the value returned by the method. For example:

    /**
     * Returns the preferred size of this component.  This method is
     * implemented so that calling the pack method on
     * an instance of this class will not change the size of the
     * window unpredictably. 
     *
     * @return the preferred size of this component. 
     */
  

---

Rule #4 (placement of tags):
All tags should begin at the start of a new line of a doc-comment, per the examples above.

---

Rule #5 (html)
You may use html tags (like <code> xxx </code>) within the doc comment to provide additional formatting of your comments. Not all html tags will work, but the most common will.

---

Rule #6 (additional content)
You may put comments into your program that are not doc comments. While the doc comments form the official public release documentation, other documentation may be useful during development.

You may include other information in doc comments beyond that specified. However, doc comments should be concise and to the point. Try to avoid simply restating what is obvious from the name of the method being documented.

---

Rule #7:
This is a simplified description of the Javadoc rules. We encourage you to examine the full set of rules at Sun's Javadoc Tool Home Page and to abide by the detailed advice therein.

What should I put in my descriptions of constructors and methods?

Descriptions of constructors and methods:

• Should state what the constructor/method DOES
• Should generally not state how the constructor/method does what it does
• Should generally not state when the constructor/method is invoked
• Should generally not state what the constructor/method "is"