Java Reference
In-Depth Information
we discuss defining classes. In the meantime, you may notice the following conventions
in our code:
We use line comments (that is, the
//
kind) for comments meant only for the code
writer or for a programmer who modifies the code and not for any other programmer
who merely uses the code.
For comments that would become part of the documentation for users of our code,
we use block comments (that is, the
/* */
kind). The
javadoc
program allows you to
indicate whether or not a block comment is eligible to be extracted for documentation.
If the opening
/*
has an extra asterisk, as in
/**
, then the comment is eligible to be
extracted. If there is only one asterisk,
javadoc
will not extract the comment. For this
reason, our block comments invariably open with
/**
.
It is difficult to say just how many comments a program should contain. The
only correct answer is “just enough,” which of course conveys little to the novice
programmer. It will take some experience to get a feel for when it is best to include a
comment. Whenever something is important and not obvious, it merits a comment.
However, providing too many comments is as bad as providing too few. A program
that has a comment on each line is so buried in comments that the structure of the
program is hidden in a sea of obvious observations. Comments such as the following
contribute nothing to understanding and should not appear in a program:
interest = balance * rate;
//Computes the interest
.
A well-written program is called
self-documenting
, which means that the structure
of the program is clear from the choice of identifier names and the indenting pattern.
A completely self-documenting program would need none of these
//
comments that
are only for the programmer who reads or modifies the code. That may be an ideal that
is not always realizable, but if your code is full of
//
comments and you follow our
convention on when to use them, then either you simply have too many comments or
your code is poorly designed.
A very simple example of the two kinds of comments is given in Display 1.8.
when to
comment
self-
documenting
Indenting
We will say more about indenting as we introduce more Java. However, the general rule
is easy to understand and follow. When one structure is nested inside another structure,
the inside structure is indented one more level. For example, in our programs, the
main
method is indented one level, and the statements inside the main method are indented
two levels. We prefer to use four spaces for each level of indenting because more than
four spaces eats up too much line length. It is possible to get by with indenting only
two or three spaces for each level so long as you are consistent. One space for a level of
indenting is not enough to be clearly visible.
