Organizing Java files and other practicalities - JavaTech: An Introduction to Scientific and Technical Computing with Java - page 150

/** This method paints the text to the screen.
* (The comment block that describes a method must be
* placed immediately before the method line.)
*/
public void paint (Graphics g) {
g.drawString ("Hello World!", 50, 25);
}
}
Note that the /**. . .*/ comments should be placed immediately before
the class, method, or variable they are describing. Running javadoc on this
file creates several hypertext documentation files such as HelloWorld.html
whose contents are shown in the Web Course Chapter 5. Since the output files are
in hypertext format, you can also use hypertext tags in the javadoc comments,
such as < br > for line breaks and list tags such as < ul >< li > abc < /li >< /ul > .
Special Javadoc tags that begin with the “@ „ symbol allow you to put spe-
cific information into the documentation output. Examples include @author ,
@param , @throws , and @return ,which specify the author of the class, a
description of a method parameter, the exceptions that might be thrown, and a
method's return value, respectively.
Over subsequent versions, javadoc has grown increasingly sophisticated
and now provides for extensive customization. The doclets API (via the
com.sun.javadoc package) allows for Java classes that can modify the out-
put from javadoc . The taglets API allows for Java classes that create cus-
tom tags. See the Javadoc reference [2] for documentation on doclets and
taglets .
5.10 Coding conventions
As with any programming language, you should strive to make your Java programs
as readable and understandable as possible, both for yourself as well as for others
who might use your code. This means clear, concise, and plentiful comments and
descriptive, informative names for classes, method, and variables. Furthermore,
a consistency in the style of the code helps both in reading and debugging your
programs.
There are a number of Java coding standards that have been proposed. For our
demonstration programs in the following chapters, we follow the guidelines set
out by noted Java guru Doug Lea. The full standard is too lengthy to include here
(see Lea [3] for the complete standard) but we give the essentials that suffice for
our short demos.