Everything is an object, Part 2

Build your first Java program

1 2 Page 2
Page 2 of 2

Remember, however, that everything inside the /* and */ is ignored, so there's no difference in saying:

/* This is a comment that
continues across lines */

The second form of comment comes from C++. It is the single-line comment, which starts at a // and continues until the end of the line. This type of comment is convenient and commonly used because it's easy. You don't need to hunt on the keyboard to find / and then * (instead, you just press the same key twice), and you don't need to close the comment. So you will often see:

// this is a one-line comment

Comment documentation

One of the thoughtful parts of the Java language is that the designers didn't consider writing code to be the only important activity -- they also thought about documenting it. Possibly the biggest problem with documenting code has been maintaining that documentation. If the documentation and the code are separate, it becomes a hassle to change the documentation every time you change the code. The solution seems simple: link the code to the documentation. The easiest way to do this is to put everything in the same file. To complete the picture, however, you need a special comment syntax to mark special documentation, and a tool to extract those comments and put them in a useful form. This is what Java has done.

The tool to extract the comments is called javadoc. It uses some of the technology from the Java compiler to look for special comment tags you put in your programs. It not only extracts the information marked by these tags, but it also pulls out the class name or method name that adjoins the comment. This way you can get away with the minimal amount of work to generate decent program documentation.

The output of javadoc is an HTML file that you can view with your Web browser. This tool allows you to create and maintain a single source file and automatically generate useful documentation. Because of javadoc we have a standard for creating documentation, and it's easy enough that we can expect or even demand documentation with all Java libraries.

Syntax

All of the javadoc commands occur only within

/**

comments. The comments end with

*/

as usual. There are two primary ways to use javadoc: embed HTML, or use

doc tags.

Doc tags are commands that start with a

@

and are placed at the beginning of a comment line. (A leading

*

, however, is ignored.)

There are three types of comment documentation, which correspond to the element the comment precedes: class, variable, or method. A class comment appears right before the definition of a class; a variable comment appears right in front of the definition of a variable, and a method comment appears right in front of the definition of a method. As a simple example:

/** A class comment */
public class docTest {
  /** A variable comment */
  public int i;
  /** A method comment */
  public void f() {}
}

Note that javadoc will process comment documentation for only public and protected members. Comments for private and "friendly" members (see Chapter 5 [of Thinking in Java]) are ignored and you'll see no output. (However, you can use the -private flag to include private members as well.) This makes sense, since only public and protected members are available outside the file, which is the client programmer's perspective. However, all class comments are included in the output.

The output for the above code is an HTML file that has the same standard format as all the rest of the Java documentation, so users will be comfortable with the format and can easily navigate your classes. It's worth entering the above code, sending it through javadoc, and viewing the resulting HTML file to see the results.

Embedded HTML

Javadoc passes HTML commands through to the generated HTML document. This allows you full use of HTML; however, the primary motive is to let you format code, such as:

/**
* <pre>
* System.out.println(new Date());
* </pre>
*/

You can also use HTML just as you would in any other Web document to format the regular text in your descriptions:

/**
* You can <em>even</em> insert a list:
* <ol>
* <li> Item one
* <li> Item two
* <li> Item three
* </ol>
*/

Note that within the documentation comment, asterisks at the beginning of a line are thrown away by javadoc, along with leading spaces. Javadoc reformats everything so that it conforms to the standard documentation appearance. Don't use headings such as <h1> or <hr> as embedded HTML because javadoc inserts its own headings and yours will interfere with them.

All types of comment documentation -- class, variable, and method -- can support embedded HTML.

@see: referring to other classes

All three types of comment documentation (class, variable, and method) can contain @see tags, which allow you to refer to the documentation in other classes. Javadoc will generate HTML with the @see tags hyperlinked to the other documentation. The forms are:

@see classname
@see fully-qualified-classname
@see fully-qualified-classname#method-name

Each one adds a hyperlinked "See Also" entry to the generated documentation. Javadoc will not check the hyperlinks you give it to make sure they are valid.

Class documentation tags

Along with embedded HTML and

@see

references, class documentation can include tags for version information and the author's name. Class documentation can also be used for

interfaces

(see Chapter 8 [in

Thinking in Java

]).

@version

This is of the form:

@version version-information

in which version-information is any significant information you see fit to include. When the -version flag is placed on the javadoc command line, the version information will be called out specially in the generated HTML documentation.

@author

This is of the form:

@author author-information

in which author-information is, presumably, your name, but it could also include your email address or any other appropriate information. When the -author flag is placed on the javadoc command line, the author information will be called out specially in the generated HTML documentation.

You can have multiple author tags for a list of authors, but they must be placed consecutively. All the author information will be lumped together into a single paragraph in the generated HTML.

@since

This tag allows you to indicate the version of this code that began using a particular feature. You'll see it appearing in the HTML Java documentation to indicate what version of the JDK is used.

Variable documentation tags

Variable documentation can include only embedded HTML and

@see

references.

Method documentation tags

As well as embedded documentation and

@see

references, methods allow documentation tags for parameters, return values, and exceptions.

@param

This is of the form:

@param parameter-name description

in which parameter-name is the identifier in the parameter list, and description is text that can continue on subsequent lines. The description is considered finished when a new documentation tag is encountered. You can have any number of these, presumably one for each parameter.

@return

This is of the form:

@return description

in which description gives you the meaning of the return value. It can continue on subsequent lines.

@throws

Exceptions will be demonstrated in Chapter 10 [of Thinking in Java], but briefly they are objects that can be "thrown" out of a method if that method fails. Although only one exception object can emerge when you call a method, a particular method might produce any number of different types of exceptions, all of which need descriptions. So the form for the exception tag is:

@throws fully-qualified-class-name description

in which fully-qualified-class-name gives an unambiguous name of an exception class that's defined somewhere, and description (which can continue on subsequent lines) tells you why this particular type of exception can emerge from the method call.

@deprecated

This is used to tag features that were superseded by an improved feature. The deprecated tag is a suggestion that you no longer use this particular feature, since sometime in the future it is likely to be removed. A method that is marked @deprecated causes the compiler to issue a warning if it is used.

Documentation example

Here is the first Java program again, this time with documentation comments added:

//: c02:HelloDate.java
import java.util.*;
/** The first Thinking in Java example program.
 * Displays a string and today's date.
 * @author Bruce Eckel
 * @author www.BruceEckel.com
 * @version 2.0 
*/
public class HelloDate {
  /** Sole entry point to class & application
   * @param args array of string arguments
   * @return No return value
   * @exception exceptions No exceptions thrown
  */
  public static void main(String[] args) {
    System.out.println("Hello, it's: ");
    System.out.println(new Date());
  }
} ///:~

The first line of the file uses my own technique of putting a : as a special marker for the comment line containing the source file name. That line contains the path information to the file (in this case, c02 indicates Chapter 2) followed by the file name. The last line also finishes with a comment, and this one indicates the end of the source code listing, which allows it to be automatically extracted from the text of [Thinking in Java] and checked with a compiler.

Coding style

The unofficial standard in Java is to capitalize the first letter of a class name. If the class name consists of several words, they are run together (that is, you don't use underscores to separate the names), and the first letter of each embedded word is capitalized, such as:

class AllTheColorsOfTheRainbow { // ...

For almost everything else: methods, fields (member variables), and object reference names, the accepted style is just as it is for classes except that the first letter of the identifier is lowercase. For example:

class AllTheColorsOfTheRainbow {
  int anIntegerRepresentingColors;
  void changeTheHueOfTheColor(int newHue) {
    // ...
  }
  // ...
}

Of course, you should remember that the user must also type all these long names, and so be merciful.

The Java code you will see in the Sun libraries also follows the placement of open-and-close curly braces that you see used in [Thinking in Java].

Conclusion

In this [article] you have seen enough of Java programming to understand how to write a simple program, and you have gotten an overview of the language and some of its basic ideas. However, the examples so far have all been of the form "do this, then do that, then do something else." What if you want the program to make choices, such as "if the result of doing this is red, do that; if not, then do something else"? The support in Java for this fundamental programming activity [is covered in Chapter 3 of

Thinking in Java

].

Bruce Eckel is the author of Thinking in C++, which won the Software Development Jolt Award for best book of 1995, and Thinking in Java, which recently won a JavaWorld 1999 Readers' Choice Award for best book. He's been professionally programming for 20 years and has been teaching people throughout the world how to program with objects since 1986. He was a voting member of the C++ Standards Committee, has written six books on object-oriented programming, and has published more than 150 articles on the subject. You can visit his Website at www.eckelobjects.com.

Learn more about this topic

Related:
1 2 Page 2
Page 2 of 2