Javadoc Clutter

Ed Gibbs, one of my favorite bloggers, writes on the usefulness of javadoc comments. (I meant to write on Alfred Thompson's thoughts on the issue last month as well, but didn't get to it.) Here's my take: If you're coding properly, you have lots of little methods, as Ed says, and they should be just about self-documenting and not really in need of comments. But, when you have code organized like this, it becomes even more important that the big picture be kept in mind somewhere. This partly means working on good class-level documentation - how the class is intended to be used for example, but it also means having good diagrams of the entire application. With this, you may realize not only how the class is intended to be used, but how it's being used in an unintended way, or how it's duplicating the functionality of this other class over here and they need to be merged into a single class.

So where do the diagrams come from? As Alfred mentions, you can use class designers like the one in Visual Studio, but my feeling is that that is only a starting point. There are so many different diagrams you can make: dataflow, inheritance, etc., but you have to keep in mind that the point of any diagram is to help the reader grok the system. What I like to do is keep a documentation wiki around, and generate some diagrams that can be added as pictures, and as a starting point for some user-defined text to help explain them.

But when you do that, eventually you're going to want hyperlinks in the text that lead back to the class, and its description, and its methods. And this is where Javadoc comes in. In the build, throw in a step that generates HTML pages from the Javadocs, and make them available to the users of the project wiki. I think this gives you the nicest combination of high-level overviews and class-level references, both of which are essential to a well-managed project.