Developers understand that code reuse necessitates a simple-to-learn interface. Typically, this leaves us adding another layer of abstraction (aka. “turtle”) to the existing turtle-pile. This is all wonderful and leaves us feeling warm and fuzzy, except that abstractions are leaky at best. Usually these new clever interfaces simplify doing whatever you need to do (as long as it is what the API author says you want to do). This means that in order to consume another’s code, I must first learn his or her clever new interface and the interfaces below it.
Recent projects have brought me to the realization that sometimes it’s better to remove a layer of abstraction. I recently built a solution that involved thermal transfer printing bar codes on pre-printed ticket stock.
The printer uses a proprietary Postscript-like language for creating fields and updating their values throughout the course of a print job. The printer also came with several half-baked utilities to almost simplify the job of getting it to print what I want, but not quite. After perusing the developer’s guide, it turned out to be as simple as sending control characters to a parallel port. I wrote a ‘driver’ in ColdFusion that reads the ticket records from the database and generates a .prn file (just ASCII control codes). Now I can simply cat the generated file to the fancy printer from any machine that has a parallel port regardless of operating system and without having to install printer drivers.
Albert Einstein is quoted as saying “Things should be made as simple as possible, but no simpler.” In the example above, I had to learn something new either way—the formatting codes or the libraries that came with the printer. The libraries failed to simplify the interaction because they did not provide a complete abstraction; I would still have to delve a layer deeper for some of the things I needed.
Think about the abstractions you provide. Do they really simplify? Will a user of your API need to delve a layer deeper? If so, you’ve only created an obstacle.
Let’s be really clever developers; let’s learn the abstractions we already have and create clever documentation for other developers.
Tags: abstraction, API, reuse
Web Monkeys with Laserbeams 
November 14, 2008 at 3:48 pm
Great perspective — very true and important. Thank you for writing it!
November 14, 2008 at 4:17 pm
I enjoyed this post, even from a non-developer perspective. There are spiritual applications here as well. Good job Jon.
November 24, 2008 at 11:25 pm
Your description reminded me of the abstraction-inversion anti-pattern
http://en.wikipedia.org/wiki/Abstraction_inversion
I’ve seen similar cases where the design of an API is lacking… or at least seemed to be lacking to me… that used to be the case with VeriSign’s merchant account gateways although I haven’t used them in a while and in that case there wasn’t a simpler alternative like the parallel port.
I’d actually be rather interested to hear what you think (as abstractions go) of the DataFaucet ORM tools… http://www.datafaucet.com … It’s all documented on the site there.
It’s got a lot of features already implemented — DDL for creating and dropping tables, gateways for searching, implicit and/or keyword searching, active records, etc.
Also, not released yet, but I’m working right now on an alternative “persistence service” option that will build db tables from your objects, without your objects needing any information about the ORM, so they’re totally separate. This was something Joe Rinehart mentioned on his blog a couple weeks ago. It’s almost ready for an initial release actually. I’ve done basic testing, just need to build a small sample application for it and write some documentation.
November 24, 2008 at 11:33 pm
On another note, whenever I see someone link to Joel’s leaky abstraction article, I always kind of brace myself for the forthcoming “therefore we should all go back to using slide-rules” speech… Nice to see your use of it was not only thoughtful but quite reasonable as well. 🙂
November 25, 2008 at 5:06 pm
@ben
I hadn’t even considered the notion outside of programming, but I suppose it applies to any collections of ideas. That gives me more to ruminate over.
@ike
I’ll have to give DataFaucet a look. Thanks for the Wiki link, too. I didn’t know the anit-pattern had a name. That certainly aids discussion when it comes up in development.