I've long been a fan of telling folks "if you want examples, take a look at the unit tests". Folks have long been disappointed with that response.

I've found maintaining a distinct "examples" tree problematic, for a number of reasons but fundamentally due to my own laziness. One set of forces pulls us toward maintaining the examples as documentation--we want the examples linked in to the other documentation and to include explanatory prose. Another set of forces pulls us toward maintaining the examples as source code--we want to make sure the examples will compile, are up-to-date with the rest of the API, and can be refactored with the rest of the codebase (so that, for example, a "Rename Method" refactoring applies to the examples as well as everything else).

Recently I've been experimenting with what seems to be a viable approach to this problem--writing examples as "literate" unit tests. In short, I keep the examples directly within the test source tree, implementing them as true JUnit TestCases, and using plain old C-style (not JavaDoc) comments to provide the prose. The JXR Java-to-HTML cross-reference generating tool can produce a hyper-linked version of those source files, and it's already built into Maven's site goal.

You can see some examples of this approach within Commons Functor.

(Literate Programming purists are likely to take issue with calling this "literate programming", but there don't seem to be many of those around these days.)

I've found this approach leads me to create a lot more inner classes in those unit tests than in my typical code. The heavy use of inner classes may be disorienting for some readers, but I suppose it isn't strictly necessary (the alternative may be to "pollute" the test tree with more files). On the positive side, this approach does a good job of allowing one to express the code in a "test first" style without resorting to showing the code as a time-series. If I can find the time I'll probably be adding some more Commons Functor examples in the next few days, so if you're interested you may want to check back then too.

It might be interesting to try to find or build greater tool support for this approach, perhaps with some custom JavaDoc doclet or java2html tool. (I keep wanting to move beyond simple text in those descriptions, although the simplicity has its appeal.)

(I'm very interested in what others think about this approach, by the way. Feel free to comment or otherwise contact me.)

It's been a long time coming (Milestone 0 was released around 9 months ago), but we've finally got around to cutting a second binary release of Axion, the open source relational database system written in Java.

This release adds a bunch of neat features including TRANSACTION_SERIALIZABLE strength transactions, a new btree index type, new data types and more.

The bulk of the work on these features was done in the latter part of 2002, but it's a little too easy for the development team to simply work from the cvs HEAD rather than preparing a binary release.

With a Milestone 1 release out of the way, we can move on to adding new features a bit more aggressively, some of which are already underway. I hope to have more frequent milestone releases in the future, and I think the rest of the team does as well. Indeed, an M2 release might be appropriate fairly soon.

I've finally started blogging. Why? Take your pick:

• I've grown tired of pontificating on our intranet Wiki.
• I've recently taken an interest in journaling in general.
• A friend has been prodding me, at first privately and recently publicly to jump on the blogging bandwagon. (To protect the innocent I won't name him here.)
• Having lurked for a couple of months on various blogs, I've decided to join the conversation.

Hopefully sometimes I'll have something interesting to say.

I'm still getting used to the Radio style and formatting rules, so please excuse any bouts of repeated editing you see here.