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.

Learning from Joel Spolsky (and Dave Winer)

Here are my comments on Joel's comments on Dave Winer's comments concerning comments. I think Dave is dead-on, but the whole issue is really more of an A-List issue than it is a general concern. I bet there's some sort of law that states that the amount of garbage increases exponentially to the number of participants; if there isn't, there should be. If you have a small blog where just a few people comment - or none, like this one - the quality of the discourse tends to be pretty high, but when you start having thousands of readers, the number of people who have their own agenda to push starts to outweigh the number with interesting feedback. I have comments enabled, and I expect to have them for the foreseeable future :)

But I still want some way to do trackbacks. I don't think the existing trackback system is able stop spam well enough to be useful, but the fact is, no one who reads Joel's post will ever find out about this one, as far as I can see; especially the casual reader who only stops by for a few seconds.