Bones and Documents

I’ve been thinking about tests and legacy code. The topic came up when I was listening to an episode of the Legacy Code Rocks podcast with the famous Michael Feathers, author of Working Effectively with Legacy Code. Andrea Goulet, one of the podcast’s hosts, and co-founder Corgibytes, a company that specializes in legacy code, made the observation that when working in legacy code, tests are like bones: They are very important to archeologists, and they stick around.

The analogy of legacy code work to archeology is a good one, but I’m not sure about the analogy between tests and bones. On one hand, bones are very important to archeology. They last a long time (or, as academics would say, they “persist in the archeological record”), and they can be tied to a particular species. But I think tests have a more important aspect than durability. The important thing about tests is that they were written down by their authors. Reading tests is more like finding documents.

When I was studying ancient literature and history in college, there was one glorious semester when I was taking a class in Roman Comedy, and a class in archeology of Roman domestic life. Once, we were having a debate in the archeology class about how private different parts of the house were, asking questions like: “guests are allowed in the atrium, but would it be awkward if some guest wandered into the kitchen?”

This type of question is difficult to answer from an archeological perspective. People have done studies like count the number of doors a person has to pass through from the street to get to a particular room, and used that as a proxy for how “private” the room is considered, but that’s a bit of a guess. Then, when I was reading Roman Comedy, I found a passage where a man starts complaining about how unwanted visitors are trampling all over his privacy because they won’t stay out of the kitchen. In my mind, that answers the question definitively: The way we know Romans felt like the kitchen was more private than the atrium is that one of them makes a joke about unwelcome visitors who aren’t polite enough to stay out of the kitchen. Mystery solved.

Going back to software for a moment: Tests, even bad or very old tests, tell us about what the authors of a system believed at the time that the system actually did. I think legacy code can be approached from two perspectives, much like the Roman house: We can do archeology or we can look at documents. Archeology is reading the source code itself, doing little refactorings, running static analyzers, figuring out when and whether a given method is called. Document-finding is about tests and documentation. If there’s a test that says test "the autoload module works like normal autoload" do (from Rails), we may not love the descriptor, but we know that the previous developers thought autoloading was a normal thing that people do, and that the code in the test represented normal autoloading. That’s a valuable piece of information. I think in terms of archeology, it’s definitely document-type evidence, not artifact-type evidence.

Let me try to tie the analogy all back together: Archeology and legacy code investigation are similar in that they both involve trying to discover more about some artifact that previous people left. In both cases, we generally can’t ask the original creators of the author what they wrote, either because they don’t work at that company any more, or because they’ve been dead for thousands of years. Legacy code investigation and (recent) archeology both have two primary modes of investigation: By inspecting the artifacts themselves, and by inspecting documents that were produced by the same people as produced the artifacts. Both modes have strengths and weaknesses, but they work well together in concert.

So next time you’re trying to understand some old piece of code that ancient peoples (or you 2 months ago) wrote, remember to examine the artifacts (code itself) and the documents (tests and commit messages) together. And check out the next episode of Legacy Code Rocks!

Till next time, happy learning!


Leave a Reply

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

You are commenting using your 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