Look under the turtle


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: , ,

5 Responses to “Look under the turtle”

  1. Doug Says:

    Great perspective — very true and important. Thank you for writing it!

  2. ben Says:

    I enjoyed this post, even from a non-developer perspective. There are spiritual applications here as well. Good job Jon.

  3. ike Says:

    Your description reminded me of the abstraction-inversion anti-pattern


    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.

  4. ike Says:

    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. 🙂

  5. jonwolski Says:

    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.

    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.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: