Summary
Elliotte Rusty Harold talks with Bill Venners about the benefits of a having single
decision maker for an API design and insights gained through writing examples that use the API.

Elliotte Rusty Harold is a prolific author of numerous books about
Java and XML, and creator of the popular Java website Cafe au Lait
and XML website Cafe con Leche. He contributed to the development of
JDOM, a popular XML processing API for Java. His most recent
book, Processing XML with Java, shows how to parse,
manipulate, and generate XML from Java applications using several XML
APIs, including SAX, DOM, and JDOM.

At a meeting of the New York XML SIG in September, 2002, Harold unveiled
an XML processing API of his own design: the XOM (XML Object Model) API.
On Cafe au Lait and Cafe con Leche, Harold described XOM like this:

Like DOM, JDOM, dom4j, and ElectricXML, XOM is a read/write API that
represents XML documents as trees of nodes. Where XOM diverges from
these models is that it strives for absolute correctness and maximum
simplicity. XOM is based on more than two years' experience with JDOM
development, as well as the last year's effort writing Processing XML
with Java. While documenting the various APIs I found lots of things
to like and not like about all the APIs, and XOM is my effort to
synthesize the best features of the existing APIs while eliminating the
worst.

In this interview, which is being published in multiple installments,
Elliotte Rusty Harold discusses the strengths and weaknesses of
the various XML processing APIs for Java, the design problems with existing
APIs, and the design philosophy behind XOM.

In Part VI. Air Bags and Other Design Principles, Harold discusses
API design principles that guided the design of the XOM (XML Object Model) API,
including enforcement of invariants, information hiding for simplicity, and
not using assertions for air bags.

In this seventh installment, Harold discusses the benefits of a having single
decision maker for an API design and insights gained through writing examples that use the API.

Design by Dictatorship

Bill Venners: What development style did you use when you created
XOM? In your talk you said, "This a Cathedral, not a Bazaar."

Elliotte Rusty Harold: So far, XOM has been a one person project. I
have written almost all the code. Other users have spotted bugs and
suggested features. Occasionally, a line or two of code has been contributed.
But basically XOM has been done entirely by me. That may change in the future.
There's currently a submission from Bradley Huffman on XPATH, which he
wrote. That might go in, but it isn't in the codebase yet.

XOM is my API. I designed it. It's not developed by majority vote. I have certainly
occasionally been convinced that I've made mistakes. Sometimes it is really
obvious. Sometimes it requires a little more argument. But ultimately, I am the
one who decides what goes in and what does not. That process contrasts with the design process
for APIs like JDOM, where occasionally things are done by vote. It certainly
contrasts with the design process for APIs like DOM, where decisions are made by a very formal
procedure of voting and consensus. I think that even if this process makes XOM
occasionally a little quirky in places—because like all people I have my little
quirks: for example, I don't like method invocation chaining—overall benevolent dictatorships create
cleaner APIs.
Having one clear vision for an API is better than compromising between many competing visions.

Design by Writing Examples

Bill Venners: What techniques did you use to help you discover where your
API was good and where it wasn't.

Elliotte Rusty Harold: I am a fan of Extreme Programming, but since I am essentially working by
myself at home, pair programming isn't an option. I do use unit tests heavily on
almost all the classes. The only areas where I don't have serious unit tests,
where I have some tests but not full coverage, are in serialization and in
parsing. Because writing unit tests for serialization and parsing is just bloody hard, so far I
haven't done it. I really need to, though, because guess where all the bugs show up?
They show up in serialization and parsing, where I don't have good unit test
coverage.

One of the things I did that helped a lot with the design of the API, as opposed
to debugging and testing it, is I went through my book Processing XML with
Java, which over the course of 1000 plus pages has many sample programs in
SAX, DOM, JDOM, TraX, and other APIs. I rewrote all those examples using
XOM. Sometimes I would realize I was missing some obvious method that
would make this easier. Also, after I got to the end of the book and I looked at
my code samples, I realized I never did use certain methods. So I took them out.
Or I only used a method once, but I could have used another method instead.
That's why I got rid of the getNextSibling and
getPreviousSibling methods I originally had, for example. It just
became obvious after translating all the examples to XOM that those methods weren't necessary.

I think implementing all those examples helped clarify a lot of the thoughts I
had about what was worth putting in the API and what wasn't. In some cases it
proved I needed new things. In other cases it proved I could afford to take
certain things out. Based on what I've heard from early adopters of XOM, it
resulted in a pretty clean API. I don't hear a lot of calls for convenience methods
that aren't there. It is very rare compared to JDOM for example, where a lot of
people ask frequently for extra methods.

Bill Venners: They do? But JDOM already has a lot of convenience
methods, and XOM has so few.

Elliotte Rusty Harold: But maybe I've got the right methods.

Bill Venners: Or perhaps it's cultural.

Elliotte Rusty Harold: Yes, maybe it's cultural. In XOM, they can see that
there's not a lot of chance of getting additional methods added. For example,
JDOM's Attribute class has eight different methods to read an attribute
value depending on whether you want to get it back as an int, a
float, a double, a Boolean, a
String, or a Martian.

Bill Venners: What you're saying is that one of the techniques that helped you
design XOM is that you used your API over and over in lots of different cases.

Elliotte Rusty Harold: Yes.

Bill Venners: You looked at your book and rewrote all your XML processing examples in
XOM, and you learned what was and was not needed in the XOM API.

Elliotte Rusty Harold: Right, exactly.

Design by Writing Tests

Bill Venners: Unit testing is a way to write clients that can give you
some insight into your API, but it seems rewriting XML processing examples from other APIs to XOM was more direct way to write clients.

Elliotte Rusty Harold: Unit tests are a way to make sure that methods do what you expect them to do. They don't really
help you decide what methods you need in the first place.

Bill Venners: That's not what the test-driven development folks would
say. They believe writing tests first in tiny iterations helps them discover a clean
design. I know you like unit tests. Do you write tests first?

Elliotte Rusty Harold: My problem with writing tests at the very first stage is that the test suite
doesn't show a compile error as a red bar. If your tests don't compile, you
can't run them through JUnit. I think if the JUnit GUI were rewritten so it
could load the test from source code rather than a compiled .class file, and then
report a compilation failure as a problem, then writing tests first would become more
plausible. I generally do write at least the signature and a simple method stub before I
write the test. Sometimes, even when I've got the method doing nothing more than returning
null, then I'll go write the test. But not before then.

So I still write the tests very early, but I don't like writing tests where the
IDE immediately puts squiggly lines underneath the code to indicate that it doesn't
compile. How annoying that is varies from one IDE to the next. It's not at all annoying
in emacs. In Eclipse it's a little annoying. In IntelliJ IDEA, it's practically impossible
to get anything done until your code at least compiles.

Next Week

Come back Monday, September 1 for the next installment of a conversation with
C# creator Anders Hejlsberg.
The final installment of this conversation with
Elliotte Rusty Harold will appear September 8.
If you'd like to receive a brief weekly email
announcing new articles at Artima.com, please subscribe to
the Artima Newsletter.