Getting Started - Java - page 50

from the layout of the program. Usually comments are only placed at the ends of lines
or on separate lines by themselves.
Java comes with a program called javadoc that will automatically extract documen-
tation from the classes you define. The workings of the javadoc program dictate when
you normally use each kind of comment.
The javadoc program will extract a /* */ comment in certain situations, but java-
doc will not extract a // comment. We will say more about javadoc and comments
after we discuss defining classes. In the meantime you may notice the following con-
ventions 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 program-
mer 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 docu-
mentation. If the opening /* has an extra asterisk, like so /** , 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 program-
mer. 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 like the following contribute
nothing to understanding and should not appear in a program:

when to
comment

interest = balance * rate; //Computes the interest.

A well-written program is what 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 // com-
ments 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 // comments, 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.

self-
documenting

Indenting
We will say more about indenting as we introduce more Java. However, the general
rule is easy to understand and easy to 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