Your Codebase Is a Garden – 5 Essential Code Maintenance Practices

What does a potted plant have in common with a large software codebase?

At first glance, they seem like completely different things. But in fact, both require regular maintenance to stay healthy and keep growing. When they’re neglected, both begin to decay in much the same way.

I take care of the dozen plants distributed around our Detroit office, ensuring they get enough water and sunlight, clearing away dead leaves and branches, repotting them when needed, and so on. It’s all part of “sharing the pain,” one of our five Value Mantras at Atomic Object.

Most of our plants are pretty easy to care for. But there’s one plant, a huge potted fern, that wasn’t doing so well. It was lush and full last summer when we opened the Detroit office, but it had been gradually declining over time. There were still healthy branches in a ring around the edges of the pot, but in the center it looked dead and leafless. I was perplexed.

Taking a Closer Look

One day, I took a closer look to see if I could figure out the problem. I noticed that what I had assumed was the base of the plant, was actually a thick clump of dozens of dead, broken-off branches, into which countless dead leaves had accumulated, forming a layer of detritus several inches thick. Among the dead branches and decaying leaves, I noticed tiny tangled roots growing up toward the surface, desperately trying to find water.

No wonder there were no healthy branches or new fronds growing in that part of the plant! No water, air, or sunlight could make it through all the dead matter. The only place young fronds could survive was around the outskirts, where the detritus wasn’t so thick.

It wouldn’t have gotten into such a desperate state if we’d just taken the time to prune away a few dead branches and leaves every once in a while. Instead, we left it to grow and grow until it was literally being smothered by the remnants of past growths.

Caring for Your Code

Just like a growing office plant, a software project needs constant maintenance to stay healthy. If you take the time and effort to properly care for it, your project can mature and stay healthy for a long time.

1. Attend to the whole codebase. When you’re caring for a plant, you need to make sure the whole plant gets enough water and sunlight, not just a few individual branches. Likewise, from time to time you should give some attention to the whole codebase, not just the part you’re focused on now. It’ll refresh your memory of how things work and give you an opportunity to notice redundancies, inconsistencies, and dead code that you wouldn’t have noticed otherwise.
2. Nip feature creep in the bud. Blindly adding new functionality to your codebase is a surefire way to end up with a tangled, sprawling mess. Before you add an option, function, class, or feature, ask yourself (and your team): Do we really need to add this? Is this the best place to put it? Does it provide important functionality that doesn’t already exist elsewhere? Taking a critical look at your codebase before you add more code will save you the time and effort of writing unnecessary code now, as well as keeping your codebase maintainable for the future.
3. Untangle living code. If you’re not careful, code has a tendency to get tangled up (or as Rich Hickey puts it, “complected“) with related code, like two vines wrapping around each other as they grow. Take the time to refactor your code, use abstractions and encapsulation, and create clear interfaces between components. Doing so will go a long way toward keeping your codebase tidy and easy to work with.
4. Prune dead code. Dead code — code that isn’t used anymore, doesn’t do anything, or is commented out — is a common nuisance, especially in large codebases. Just like the dead leaves and branches in the fern, dead code accumulates in your codebase, making it harder to understand and maintain. If you notice dead code that has been hanging around, remove it. And, of course, be vigilant about not leaving behind dead code yourself!
5. Divide overgrown components. When ferns and certain other types of plants get too big, you can divide them into multiple, smaller specimens. If your codebase gets too big, you can use the same approach. Identify groups of related components, and split them out into stand-alone libraries with well defined APIs. The same approach works on a smaller scale, too. Try splitting overgrown classes into multiple smaller classes, or refactoring overgrown functions into smaller functions.

Drastic Measures

Of course, if you just let your codebase grow and grow, adding more code and new features without maintaining the project as a whole, it will begin to stagnate and choke with technical debt. Like the fern, you’ll only be able to develop new features around the periphery, while the existing core of the software will wither and rot from neglect.

If it gets to that point, you may find there’s no alternative but to hunker down and cut away the dead or dying code to make room for a new, healthier implementation to sprout, giving you another chance to tend properly to the project. It’s not quick, it’s not easy, and it’s not fun, but sometimes it’s the only thing to do if you want to ensure your project’s ongoing health.

Similarly, I decided some drastic measures were needed to revive the fern. One day after work, I brought in some pruning shears and started cutting away the dead branches and sweeping out the detritus. It has been a few months since then, and just as I hoped, new fronds are beginning to emerge from the core. The regrowth is a gradual process, but I know that in the end it will be a healthier plant than if I had let it keep going down the same path.