This chapter is from the book
This chapter is from the book
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:
http://java.sun.com/j2se/1.3/docs
You also can download all this documentation for faster browsing on your own computer. The documents are more than 23MB in size and are available from the following page: