Java Reference
In-Depth Information
This is where editors or technical writers can make a huge difference to a group, even when
those editors or technical writers are other members of the programming staff. Having a
second person read over your comments can be just as important as having someone else read
over and review your code (and we all do that, right?). If the editor has trouble understanding
your documentation, then other readers will have trouble, too. Establishing a review process
that includes the documentation will help the organization and improve your comments. It
may seem to take longer, but it is one of those things that will save huge amounts of time in
the long run (where the long run is actually shorter than the time spent on the overall project).
It is also an indication, and perhaps the output, of a conscious design process for the system
being documented. Good design is hard, and often describing a design is a necessary part in
making the beginnings of a design mature. Writing the javadoc can be an aid in this matura-
tion, and can help others understand why the system is the way it is.
[
22
]
Actually, when I first started programming, a comment was indicated by having a “C” character in
column 1 of the card, just before the sequence number. Go ask your father, or look it up on Wikipedia.
