I was just re-reading Mr. Ed’s Get Your Filthy Tags Out Of My Javadoc, Eugene, an article he posted way back in August. Mr Ed thumps the table and demands that Javadoc be simple, terse and free of HTML tags.
In my little world, Javadoc is what you look up when you don’t have access to the source. If you do have access to the source, you go and look at whatever class or method you are interested in and – hey presto – you have both Javadoc comments _and _the source. So I only ever seem to look up Javadoc for source-free1, third-party libraries.
But different people work in different ways, and some of my coworkers rely on Javadoc to understand the system they are building, even while it is being built. That is why I am thorough about putting Javadoc on all the code, and insist that others do likewise.
The one problem with my Javadoc is that I rarely, if ever, generate the HTML, meaning the finished result could be full of bad formatting and stupid errors (is it @return or @returns?) and I wouldn’t know.
So here is my Christmas Wish for Java. I would like some serious Javadoc support from my IDE. I’m thinking WYSYWIG, in-line Javadoc editting. That should make most formatting problems – like putting in paragraph tags – go away, and the rest bleeding obvious. Syntax checking should also be extended into the Javadoc comment to catch errors such as missing Javadoc or @param tags that don’t match the argument list.
The integration can’t be too far away – there are plenty of syntax checkers, and also some Javadoc editors already out there.
1 “source-free” being the opposite of “free-source”.
My latest assignment, a terminal based, C++ application, is a pleasant change from the web based, Java applications that I had been working on for the last year. Even with Java’s advantages over C++, I suspect it would take longer to build a web version of this application than a terminal version.
A typical web application consists of a bunch of little programs, all doing this:
Early on, the Java people standardised the interface to these little programs and called them servlets.
In constrast, a terminal application has a bunch of subroutines that all look like this:
Not nearly as complex. And because the code is not stopping and starting with each interaction, there are no session state bugs, fewer security issues, and it really is about half the code.
Aaron Watters puts it succinctly:
Unrolling the application at each point where you need to wait simply turns the code inside out…
Of course, the reason why we write our applications inside-out is that it scales much better than if we don’t. What if there was a way to build scalable applications “inside-in and outside-out”? Jeremy Hylton points to a number of papers and projects addressing this problem.