Java Reference
In-Depth Information
release with a class called
Watchdog
for restarting processes. This isn't terrible, but it
breaks the established pattern of people's job titles that previously existed.
It is also incredibly important to realize that software changes a lot over time. A per‐
fectly apposite name on release 1 can become highly misleading by release 4. Care
should be taken that as the system focus and intent shifts, the names are refactored
along with the code. Modern IDEs have no problem with global search and replace
of symbols, so there is no need to cling to outdated metaphors once they are no
longer useful.
One final note of caution—an overly strict interpretation of these guidelines can
lead the developer to some very odd naming constructs. There are a number of
excellent descriptions of some of the absurdities that can result by taking these con‐
ventions to their extremes.
In other words, none of the conventions described here are mandatory. Following
them will, in the vast majority of cases, make your code easier to read and maintain.
However, you should recall George Orwell's maxim of style—“Break any of these
rules rather than say anything outright barbarous”—and not be afraid to deviate
from these guidelines if it makes your code easier to read.
Above all, you should have a sense of the expected lifetime of the code you are writ‐
ing. A risk calculation system in a bank may have a lifetime of a decade or more,
whereas a prototype for a startup may only be relevant for a few weeks. Document
accordingly—the longer the code is likely to be live, the better its documentation
needs to be.
Java Documentation Comments
Most ordinary comments within Java code explain the implementation details of
that code. By contrast, the Java language specification defines a special type of com‐
ment known as a
doc comment
that serves to document the API of your code.
A doc comment is an ordinary multiline comment that begins with
/**
(instead of
the usual
/*
) and ends with
*/
. A doc comment appears immediately before a type
or member definition and contains documentation for that type or member. The
documentation can include simple HTML formatting tags and other special key‐
words that provide additional information. Doc comments are ignored by the com‐
piler, but they can be extracted and automatically turned into online HTML docu‐
mentation by the
javadoc
program. (See
Chapter 13
for more information about
javadoc
.) Here is an example class that contains appropriate doc comments:
/**
* This immutable class represents <i>complex numbers</i>.
*
* @author David Flanagan
* @version 1.0
*/
public
class
Complex
{
/**
