Comments

[Page 811 (continued)] Comments Java recognizes two types of comments. C-style comments use the same syntax found in C and C++. They are delimited by /* ... */ and //. The first set of delimiters is used to delimit a multiline comment. The Java compiler will ignore all text that occurs between /* and */. The second set of delimiters is used for a single-line comment. Java will ignore all the code on the rest of the line following a double slash (//). C-style comments are called implementation comments and are mainly used to describe the implementation of your code. Documentation comments are unique to Java. They are delimited by /** ... */. These are used mainly to describe the specification or design of the code rather than its implementation. When a file containing documentation comments is processed by the javadoc tool that comes with the Java Development Kit (JDK), the documentation comments will be incorporated into an HTML document. This is how online documentation has been created for the Java library classes. Implementation Commenting Guidelines Implementation (C-style) comments should be used to provide an overview of the code and to provide information that is not easily discernible from the code itself. They should not be used as a substitute for poorly written or poorly designed code. In general, comments should be used to improve the readability of the code. Of course, readability depends on the intended audience. Code that is easily readable by an expert programmer may be completely indecipherable to a novice. Our commenting guidelines are aimed at someone who is just learning to program in Java. [Page 812] Block Comments A block comment or comment block is a multiline comment used to describe files, methods, data structures, and algorithms: /* * Multiline comment block */ Single-Line Comments A single-line comment can be delimited either by // or by /* ... */. The // is also used to comment out a line of code that you want to skip during a particular run. The following example illustrates these uses: /* Single line comment */ System.out.println("Hello"); // End of line comment // System.out.println("Goodbye"); Note that the third line is commented out and would be ignored by the Java compiler. In this text, we generally use slashes for single-line and end-of-line comments. And we frequently use end-of-line comments to serve as a running commentary on the code itself. These types of comments serve a pedagogical purposeto teach you how the code works. In a "production environment" it would be unusual to find this kind of running commentary. Java Documentation Comments Java's online documentation has been generated by the javadoc tool that comes with the Java Development Kit (JDK). To conserve space, we use documentation comments only sparingly in the programs listed in this textbook. However, javadoc comments are used more extensively to document the online source code that accompanies the textbook. Documentation comments are placed before classes, interfaces, constructors, methods, and fields. They generally take the following form: /** * The Example class blah blah * @author J. Programmer */ public class Example { ... Note how the class definition is aligned with the beginning of the comment. Javadoc comments use special tags, such as author and param, to identify certain elements of the documentation. For details on javadoc, see: http://java.sun.com/reference/docs/index.html