Apologies for the contrived metaphor. I can’t get this one out of my head.

Code is like clay. The goal is to never let it harden.

The metaphor itself—this idea of freshness—isn’t that novel. GitHub already has the idea of stale branches. Detectives and hunters might say that a trail went cold.

But freshness alone isn’t sufficient to describe what I’m talking about. Fruit goes rotten, bread gets moldy,soda goes flat if it’s left out for too long. You can slow the process, but mainly you just try to consume your food before it spoils. Once it goes bad, it costs more to salvage the food than it would be to replace it.

So if the food freshness analogy falls short, what am I trying to talk about? The important part for code isn’t newness or freshness of the code itself. What’s important is how easy it is to change, to reshape, to mold.

(Disclaimer: the last time I played with clay was probably elementary school? If anyone wants to buy me a Groupon for a clay spinning class I’d be down.)

Working with fresh code is like working with fresh clay, easy to manipulate. Working with stale code that hasn’t been touched for a long time is like working with dried-out clay: it’s hard and brittle, easy to break. And the half-life on code freshness is short, so part of our job as software custodians is to keep it fresh by proactively molding it.

I’m not original

I’m not the first person to compare code to clay. A cursory Google got me this:

In this case the point is that it’s essentially free to throw out your code and start over because changing and rewriting a chunk of code is cheaper than an equivalent change would be on anything that requires physical materials.

While this is trivially true, I don’t think it applies to most of the code we care about because code we care about almost universally lives in a complex system. Even with the most modular possible design with the strictest separation of concerns, changes to code within a complex system can have unintended and unpredictable ripple effects.

On a more practical level: how often are software teams given the space to do a complete rewrite of a component? (Arguably, software practitioners shouldn’t ask management for bandwidth to rebuild things, we should just collectively support each other making shit more maintainable.)

Another use of the metaphor is this blog post from 2017. that uses the clay-hardening metaphor for frameworks (note: the post quotes someone I don’t exactly want to promote).

I also discovered a startup in Brooklyn called Clay.

Why not let it harden?

Metaphors break down quickly, like a brick that wasn’t fired properly 😜

(Okay so I actually looked up what happens when bricks aren’t fired. There’s actually a whole type of masonry that uses air-dried bricks, which makes perfect sense considering that that’s how many buildings have been constructed throughout history. I even found this article describing how unfired clay bricks can be used in environmentally-friendly building design. Pretty neat.)

Once your code becomes load-bearing, it’s no longer a stand-alone artifact. It’s part of (what I consider to be) a living, breathing system.

Your system isn’t just the software running on servers. Your system includes all the people who interact with it: developers, testers, operators, users, support teams.

Your system is messy and complex and constantly changing, even when your code doesn’t change.

And since we can never have perfect mental models of our complex systems, the next best thing is to continuously update our imperfect mental models.

There are many ways to do so, and the Learning From Incidents community is a great resource to learn from about the topic. What I’m proposing is a baby-steps approach.

Constantly adjusting our understanding. Constantly learning.

When we treat out code like clay that we want to stay pliable,

Not just code

I was hesitant to use “code” in the metaphor. The catchiness of won me over.

But this 100% applies to docs, webpages, videos, and any other knowledge that’s been captured in a static format.

For publications can’t be updated in-place, including dates is critical. It would even be a great start if we starting marking documents as stale or otherwise highlighted the “last updated” attribute.

Hooray for clay

Now I’m going to share the different types of clay I was thinking about while writing this post 😁