This chapter is from the book

Comments

One of the most important ways to improve the readability of your program is
to use comments.

New Term

Comments are information included in a program strictly for the
benefit of humans trying to figure out what's going on in the program. The
Java compiler ignores comments entirely when preparing a runnable version of a
Java source file.

There are three different kinds of comments you can use in Java programs, and
you can use each of them at your discretion.

The first way to add a comment to a program is to precede it with two slash
characters (//). Everything from the slashes to the end of the line is
considered a comment, as in the following statement:

int creditHours = 3; // set up credit hours for course

In this example, everything from the // to the end of the line is a
comment and is disregarded by a Java compiler.

If you need to make a comment that takes up more than one line, you can begin
it with the text /* and end it with the text */. Everything
between these two delimiters is considered as a comment, as in the
following:

/* This program occasionally deletes all files on
your hard drive and renders it completely unusable
when you spellcheck a document. */

The final type of comment is meant to be computer-readable as well as
human-readable. If you begin a comment with the text /** (instead of
/*) and end it with */, the comment is interpreted to be
official documentation on how the class and its public methods work.

This kind of comment then can be read by utilities such as the
javadoc tool included with the SDK. The javadoc program uses
official comments to create a set of HTML documents that document the program,
its class hierarchy, and its methods.

All the official documentation on Java's class library comes from
javadoc-style comments. You can view current Java 2 documentation on
the Web at the following page: