Java Reference
In-Depth Information
separated by commands or other lines of code. Programmers may use a block
comment at the beginning of a program to describe the entire program, or in
the body of a program to describe the function of a specific method.
A second type of block comment, called a doc comment , or a documenta-
tion comment, begins with a forward slash followed by two asterisks (/**) and
ends with an asterisk followed by a forward slash (*/). Doc comments are meant
to provide a concise summary of the code, not to comment on specific lines of
code. Doc comments can be extracted to HTML files using the javadoc tool. For
more information on the javadoc tool, see Appendix E.
A line comment , or single line comment, is a comment that spans only a
single line or a part of a line. Line comments begin with two forward slashes (//),
which cause the rest of the line to be ignored during compilation and execution.
Line comments have no ending symbol. A line comment is useful especially
when describing the intended meaning of a single line of code, whereas the block
comment generally is more useful when describing larger sections of code. Table
2-2 shows the general form of block, doc, and line comment statements.
Table 2-2
Comment Statements
/* block comments */
/** doc comments */
// line comments
General form:
To insert explanatory comments in a program as internal documentation.
Purpose:
Examples:
1. /*Chapter 2: Anita's Antiques Splash Screen
Programmer: J. Starks
Date: September 3, 2007
Filename: Anita.java
Purpose: This program displays the name, address,
and Web site address for a company as a console application.
*/
2. /**
* Returns an Image object that can be painted on the screen.
* The URL argument must specify an absolute {@link URL}.
* The name argument is a specifier relative to the URL.
* <p>
* @param url a URL giving the base location of the image
* name and the location, relative to the URL
* @return the image at the specified URL
* @see Image
*/
3. // The following section sets the object's properties.
In the code for the Welcome to My Day application, a comment header
identifies the application, programmer, date, and purpose of the Welcome to My
Day program. Figure 2-17 shows the comment header in block comment format.
Later in the code, a line comment will explain the code used to construct the
system date.
 
Search WWH ::




Custom Search