After finishing Brand‘s How Buildings Learn a few weeks ago, I picked up another Brand book: The Clock of the Long Now which discusses (among other things) how one would design a clock intended to keep accurate time for 10,000 years. Chapter 11 lists the key design principles that the clock’s principal designer decided were most important to the clock’s success or failure. The principle that caught my eye was transparency.

(segue from discussion of clock design to software design)

Transparency is the quality of how easy (or hard) it is to understand how a mechanism works. Upon reflection, one of the reasons that I favor the pure Ajax/REST web architecture I described earlier is because it’s easy to mentally separate into three parts (browser, wire, server) and it’s easy to understand how these parts interact (HTTP requests from browser to server via wire; HTTP responses from server to browser via wire). Why is this ability to compartmentalize subsystems desirable? Because it’s easy to debug when something inevitably goes wrong.

But there’s a tension here; abstraction in software is supposed to be a good thing. The pace at which we can develop software has increased substantially for those of us who don’t have to worry about (for instance) pointers, packets, and concurrent access to persistent storage. Yet anyone who’s tried to debug a problem within an überframework will tell you that it’s hard to figure out where the error’s occurring (their code or your code), let alone fix it. This tension was described in Joel Spolsky’s the Law of Leaky Abstractions article. Net: all abstractions are imperfect, and when a mechanism underlying an abstraction fails, it’s difficult to understand and remediate the problem since the abstraction previously allowed you to remain blissfully ignorant of the underlying mechanism.

So from a design point of view, both abstraction and transparency have merit. Abstraction reduces the amount of detail one needs to master in order to accomplish a task or apply a concept. Transparency makes it easy for new team members to understand the flow of the system and allows developers and administrators to quickly track down and resolve problems. So how to find a balance between these two qualities?

I have some not-fully-formed thoughts on this question, so I’ll save them for a later entry, but I’d be happy to hear others’ thoughts in the meantime.