Working in Castle Legacy

Certain terrain lends itself to human flourishing. Food, water, shelter… often next to a source of wealth or trade.

lovely terrain, ready for business

Because the terrain drives demand humans settle, destroy, and resettle in the same desirable locations… often over centuries.

If we look at the historical record, the prosperity of a good location is often marked by violence. There are still layers of burned ash and melted nails under Rome, and spearheads and arrowheads under most cities.

prosperity is often accompanied by conflict

Conflict doesn’t always bring progress. Sometimes a rival civilization makes an example of a city, or their own internal conflict causes them to fail. The ashes and wreckage too find their way into the earth.

unsolved conflict causes ruin

But if the ground is good, someone will always start again.

and you have to clean up an restart on the ashes

This cycle can continue in desirable locations for centuries. As successive generations or civilizations build on top of the infrastructure left by the previous occupants, the future settlement is shaped both by the natural contours of the land and by the remaining previous infrastructure. The pile of dirt that contains all these layers of histories is called a “tell.”1

but what you build is informed by what is there before

Many great European cities contain such tells. Many owe their shape and character to medieval or even Roman architecture and decisions: Paris’s 14th century sewers2, or Roman aqueducts3 and roads and bridges4.

and history will repeat itself on grander scales

The original terrain or the changes people made to that terrain drives any new construction. The new builders will take to jumpstart their progress. It’s no surprise that the surviving bits of those old European cities that stay maintained and used are invisible infrastructure. Sometimes the original plan conflicts with our mental image of the construction in surprising ways.5 Other times you’ll see the same triumphs and mistakes repeated time and time again. This makes sense… there are only a few places to build a port, defend a tower, or build a road.

what is below is just as true and real as what is above ground

Just like the physical construction a legacy software code case contains contains historical layers… where each successive attempt and architecture on the same business domain borrows abstractions and concepts from the previous iterations.

you knew we weren't talking about physical history, right?

Digging through the digital “tell"s that I’ve worked on before, I’ve found these layers in:

  • Routers / URLs6
  • Namespaces
  • Business Rules (Permissions!)
  • Glue Code
  • Legacy APIs
  • Code Specific to Old Clients or Business Models

Thinking about software as layers of a city7 has helped me a lot. When working in a legacy software “tell,” I’ll find myself shifting my mindset from an engineer to that of an archaeologist. A digital archaeologist understands that the previous occupants of this terrain might have had similar goals, but a different language, culture, belief system that drove their decisions. They’ll take a human perspective to the remains they find, and use some forensic tools8 to try and build a picture of the story.

When working in a digital "tell”, it is more important to learn to dig than to build. It’s partly why I love vim: it’s whole paradigm centers around the critical skill of editing what is already there rather than focusing on writing from scratch.

I’ve also carried this thinking into writing “new” code. What kind of decisions are going to be so ingrained into this “terrain” that I should really document for future generations.


  1. Tell (archaeology) - wikipedia.org 

  2. Paris sewer - wikipedia.org 

  3. Aqua Virgo - Wikipedia.org 

  4. Ponte di Tiberio (Rimini) 

  5. My favorite example: NYC doesn’t really have alleys in Manhattan because of the designed grid. Cortland Alley - 99percentinvisible.com 

  6. I once read about a decision for Twitter URIs that slowed down response time… as the platform grew, they couldn’t undo the change without breaking the value of the platform, so they were stuck with the decision. (Trying to find the source.) 

  7. I think I have to credit Vernor Vinge’s book A Deepness in the Sky for planting this image in my head. Thinking about this process in software development as building a continous stack over millenia… fascinating. Great book. 

  8. Spelunking in Git - evantravers.com 


🔖