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.