By Barry Burd

This Java listing has an enhanced version of a sample program. In addition to all the keywords, identifiers, and punctuation, it has text that’s meant for human beings to read.

/*
 * Listing 3-6 in "Java For Dummies, 6th Edition"
 *
 * Copyright 2014 Wiley Publishing, Inc.
 * All rights reserved.
 */
/**
 * The Displayer class displays text 
 * on the computer screen.
 *
 * @author  Barry Burd
 * @version 1.0 10/24/13
 * @see     java.lang.System
 */
public class Displayer {
    /**
     * The main method is where
     * execution of the code begins.
     *
     * @param  args   (See Chapter 11.)
     */
    public static void main(String args[]) {       
        System.out.println("I love Java!");  //I? You?
    }                                             
}

A comment is a special section of text inside a program whose purpose is to help people understand the program. A comment is part of a good program’s documentation.

The Java programming language has three kinds of comments:

  • Traditional comments: The first five lines of the listing form one traditional comment. The comment begins with /* and ends with */. Everything between the opening /* and the closing */ is for human eyes only. No information about “Java For Dummies, 6th Edition” or Wiley Publishing, Inc. is translated by the compiler.

    The second, third, fourth, and fifth lines in Listing 3-6 have extra asterisks (*). They’re called extra because these asterisks aren’t required when you create a comment. They just make the comment look pretty.

  • End-of-line comments: The text //I? You? in the listing is an end-of-line comment. An end-of-line comment starts with two slashes and goes to the end of a line of type. Once again, the compiler doesn’t translate the text inside the end-of-line comment.

  • Javadoc comments: A javadoc comment begins with a slash and two asterisks (/**). The listing has two javadoc comments — one with the text The Displayer class . . . and another with the text The main method is where. . . .

    A javadoc comment is a special kind of traditional comment. A javadoc comment is meant to be read by people who never even look at the Java code. But that doesn’t make sense. How can you see the javadoc comments?

    Well, a certain program called javadoc (what else?) can find all the javadoc comments in the listing and turn these comments into a nice-looking web page. This figure shows the page.

    image0.jpg

Javadoc comments are great. Here are several great things about them:

  • The only person who has to look at a piece of Java code is the programmer who writes the code. Other people who use the code can find out what the code does by viewing the automatically generated web page.

  • Because other people don’t look at the Java code, other people don’t make changes to the Java code. (In other words, other people don’t introduce errors into the existing Java code.)

  • Because other people don’t look at the Java code, other people don’t have to decipher the inner workings of the Java code. All these people need to know about the code is what they read on the code’s web page.

  • The programmer doesn’t create two separate things — some Java code over here and some documentation about the code over there. Instead, the programmer creates one piece of Java code and embeds the documentation (in the form of javadoc comments) right inside the code.

  • Best of all, the generation of web pages from javadoc comments is automatic. So everyone’s documentation has the same format. No matter whose Java code you use, you find out about that code by reading a page like the one in the figure. That’s good because the format is familiar to anyone who uses Java.