Identifier Naming - Writing Self-Commenting Code

Commenting

The Java programming language provides three different ways to add comments to your source code. Using comments is a great way to add documentation directly to your code, and you can place them anywhere in a source-code file. The javac compiler ignores all three types of comments when it compiles the source code. However, special comments known as javadoc comments can be used by the javadoc tool to create professional-quality source code documentation for your programs. All three types of comments are discussed in detail in this section.

Single-Line Comments

You can add single-line comments to Java programs using the characters // as shown below:

 // This is an example of a single-line comment

The compiler ignores everything appearing to the right of the double back slashes up to the end of line.

Multi-Line Comments

Add multi-line comments to Java programs using a combination of /* and */ character sequences as shown here:

 1         /* This is an example of a multi-line comment. The compiler ignores 2          * everything appearing between the first slash-asterisk combination 3          * and the next asterisk-slash combination. It is often helpful to end 4          * the multi-line comment with the asterisk-slash sequence aligned to 5          * the left as shown on the next line. 6          */

Javadoc Comments

Javadoc comments are special multi-line comments that are processed by javadoc, the Java documentation generator. The javadoc tool automatically creates HTML-formatted application programming interface (API) documentation based on the information gleaned from processing your source files, plus any information contained in javadoc comments.

Javadoc comments begin with the characters /** and end with the characters **/ . Javadoc comments can contain descriptive paragraphs, doc-comment tags, and HTML markup. Example 1.3 shows a file named  TestClass.java that contains embedded javadoc comments.

Example 1.3: TestClass.java

 1       /********************************************************** 2        TestClass demonstrates the use of <b>javadoc</b> comments. 3        @author Rick Miller 4        @version 1.0, 09/20/03 5       **********************************************************/ 6       public class TestClass { 7 8          private int its_value; 9 10         /** 11         * TestClass constructor 12         * @param value An integer value used to set its_value 13         **/ 14         public TestClass(int value){ 15           its_value = value; 16         } 17 18         /** 19          *getValue method 20          * @return integer value of its_value 21          **/ 22          public int getValue(){ 23            return its_value; 24          } 25 26         /** 27          * setValue method 28          * @param value Used to set its_value 29          **/ 30          public void setValue(int value){ 31            its_value = value; 32          } 33       }

Generating Javadoc Example Output

Figure 1-2 shows the javadoc tool being used in the UNIX environment to create API documentation for the  TestClass.java file:

Figure 1-3 shows the results of using the javadoc tool to process the  TestClass.java file:

Figure 1-3: javadoc Tool Being Used to Generate TestClass API Documentation

For a complete reference to the javadoc tool and the different doc-comment tags available for use, consult either the java.sun.com web site or the Java in a Nutshell book listed in the references section at the end of this chapter.