Java: The Good Parts

Chapter 7. Javadoc

All programmers know that it is important to comment their code and write complete documentation 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 written 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 ...