Java Reference
In-Depth Information
Chapter 7. Javadoc
All programmers know that it is important to comment their code and write complete docu-
mentation for the system in which their code is a component. We know that the documentation
is necessary to allow others to use our code. We know that comments are needed to explain
what we are doing (or trying to do), so that when others read our code, they can understand
it. We also realize that the “other” who needs these comments and documentation to help read
our code could well be ourselves six months from now when a high-priority bug has been
filed. Comments and documentation are very important.
All programmers also know that it is important to floss, to bathe regularly, to wear seatbelts
and not talk on cellphones in the car, and to dress for success. And like all of these other things
that we ought to do, when the pressure is on and deadlines loom, we tend to “forget” to do
those things. After all, they don't directly lead to getting the code working. And they can be
added later.
In times of stress, the first thing to go is the documentation. Comments are embedded in the
code and so can be written along with it, but given enough deadline pressure we all find that
the code is “self-documenting.” Documentation, on the other hand, has traditionally been writ-
ten outside of the code, often by another person (a tech writer), often after the code has been
written, and often badly. Doing either later is never a good idea. In most cases, going back and
adding comments or documentation never happens. Even when it does, the results are sketchy
at best.
The Java platform doesn't solve this problem, but it makes the production of useful docu-
mentation much easier than it is in other environments. Java allows real documentation to be
embedded with the code being documented, so that the two can be produced at the same time
and, even more importantly, changed at the same time. The mechanism for this is Javadoc,
which is definitely a good part of Java.
The Basics
When I first started programming, there was only one way to mark comments. When you
wanted to have a comment in the code, you started a line with /* and then wrote your com-
Search WWH ::

Custom Search