Java Power Tools

Part VIII. Technical Documentation Tools

Eeyore was saying to himself, “This writing business. Pencils and what-not. Over-rated, if you ask me. Silly stuff. Nothing in it.”

—“A House Is Built at Pooh Corner for Eeyore,” The House at Pooh Corner, A. A. Milne

A perfectly designed project is meaningless without good documentation to back it up. No matter how well it is designed, without a path to lead new developers up to your stride you may as well write spaghetti code. Without documentation to explain to users how one goes about using your project it will never gain popularity beyond a small group of people (often the developers themselves…and perhaps their moms).

Some proponents of agile develoment would have it that the source code itself should provide sufficient technical documentation for all purposes. There may be some merit in this statenent. After all, the source code is always up to date. However, looking at the code alone is a difficult way to understand an application. Comments are still essential to explain why a class does what it does: lines of code do a poor job of explaining business logic and design decisions. This is why it is still a good idea to document your classes in as much detail as reasonably possible.

Tools can help automate, complete, and enrich your documentation process. Tools such as Javadoc, SchemaSpy, and Doxygen can be used to produce decent, up-to-date, accurate, and reasonably usable online documentation, including (for the latter two) graphical database ...