In the late David Foster Wallace’s Infinite Jest, several of the main characters participate in a grand scale “Scorched Earth” style turn-based artillery game on a set of tennis courts. The object for each player was to lob tennis balls across court to opposing player’s targets where the balls represent some sort of ballistic warhead complete with a damage radius.
At one point it starts snowing, and one of the players argues that the damage caused by a recent “explosion” would not be as great due to the snow. One of the other players retorts that “It’s snowing on the map, not the [gosh darn] terrain!”, meaning that there was a confusion between where the line lay between the game world and that which represented the game world — that is, the terrain and the map.
It seems to me that there is a similar struggle going on within software engineering: between the software we write (the terrain), and that which describes the software (the map). Typically the “map” to software’s “terrain” has been documentation. One of the eternal (or more accurately: perennial) issues in the projects that I’ve been a part of has revolved around the tension of documentation.
In a previous project of years past, we were told to document every single method and variable. That of course didn’t work out since at that point, you get a map that perfectly describes (or even over-describes) the terrain. Beyond the maintenance nightmare (and gross violation of the DRY principle), when your “map” effectively covers your “terrain”, you start to call into question just who is supposed to be describing who.
Thankfully I’ve spent the vast majority of my time on the other end of the spectrum, more toward the realm of (attempting) “self-documenting code”, supported by languages that are designed more for humans than computers. This is because in-line comments as documentation is not the entire story — code can be used to document itself — and this is where things start to get interesting.
Some advocate that unit tests should serve as a primary source of documentation. Neal Ford said in a recent talk that the first thing he does when he returns to a project after being away is not to catch up on documentation or even the codebase, but is to read the tests.
Unfortunately I have a passive-aggressive approach to writing documentation, in that when I’m told to write it for its own sake, I actually end up writing less. So if it starts sinking into my head that writing tests is like writing documentation, I’m likely to just write fewer tests.
But this idea goes further still: with so-called Behavior Driven Development (BDD) we start approaching an “executable specification”. With BDD the idea is almost completely turned around and the software becomes the map to describe the terrain of behaviors.
I’m not sure what I think about BDD yet, or for that matter even TDD. It may be that they are super productive, super-collaborative and error-less ways to develop software — but they are also extremely intrusive. I think it would be difficult to be lukewarm about either of the “DD”s since it requires such a significant buy-in.
Fortunately self-describing code found another way into my life.
In my most recent project, we used an internal DSL, partly for ease of development, but also, as a nice side-effect, for its self-documenting nature. Internal DSLs (more or less by definition) aim to be more readable than the host language in which they reside. This makes for code that more or less matches anything that I would put in a javadoc comment.
In many ways I think it makes sense to write entire applications in a combination of various DSLs. This isn’t much of a stretch since we basically do this already (SQL in the DA layer, declarative UI languages in the presentation layer).
It seems that most “business” layers would additionally benefit from their own DSL. What’s more is that we’re starting to see tools that will aid in generating DSLs, such as Language Workbenches, and on a much smaller scale, Groovy’s MetaBuilder.
As we migrate more toward each piece of an application being written in a language that perfectly describes the domain, perhaps we’ll even live to see the death of the in-line comment in our lifetimes.
Incidentally, if you want to learn more about DSLs and how you might benefit from them (and you live in the Chicago area), then come to my talk “Using Groovy to Create DSLs: A Real-World Case Study” at the first ever Chicago Groovy User Group on January 13th 2009.