Maintainable Code as a Competitive Advantage

This isn't a post extolling maintainability as just a virtue. If you're reading this, I'm guessing you agree that good code is better than bad code, and that maintainability is a big contributor to good code. However, the difference it actually makes isn't always obvious, especially during early iterations.

Writing good, maintainable code takes time and effort. When does it pay off?

What is "good", anyway?

When I think of good code, I think of some combination of these things:

• Naming of variables, functions and files
• Structure of code and files
• Explicitness

Each of those things stem from the same concept: humans are the ones reading and writing code.

Quality of code should be measured by how easy it is for humans to understand and modify it.

From a maintainability standpoint, "good" code is easily understood by the greatest number of people, "bad" code is hard to understand for most.

However, the computer doesn't care much about those things. As long as the code you wrote is syntactically correct, it'll happily execute your instructions.

Why not optimize for development speed, then?

Have you ever stayed up late working on a personal project?

It's really exciting to iterate quickly, getting ideas out of your head and onto the screen.

Those projects are the ones that get a lot of developers into coding, myself included. It's exhilarating to see your ideas come to life.

It slows down that process a lot to spend time thinking how future developers might interact with this code, how you might need to change it in the future and which choices leave the most doors open. Worrying about maintainability is kind of a drag on that process.

So, it's totally ok to ignore those things. Without those quick hits of dopamine on each successful build, many of those projects never get off the ground.

Those projects are about learning and prototyping. They’re not meant to last.

What about when code does need to last?

When the code you write is for a company or your own startup, it suddenly matters a lot if it lasts. Code written quickly and recklessly has an expiration date.

When you build with an emphasis on finishing a feature as quickly as possible, you can get things up and running, but you can only pray that things always follow the happy path. But things out of your control can change, and those things are risks.

When you build maintainably, you can sleep well knowing that things will go wrong, but you’ve designed your software to make it easy to identify problems and be precise with the debugging and resolution.

Maintainable code has clear inputs and outputs. It produces intermediate artifacts so that a single failure doesn't require fully restarting a workflow. It has tightly scoped files that each do one thing really well.

Each time you consider those things, you enable future maintainers to quickly diagnose problems and confidently react to them.

How can I convince my manager?

Writing more maintainably slows down the release of features. Neither devs nor product managers should be interested in slowing down getting features released.

So how can we make the case that maintainability isn't just a nice idea, but actually beneficial to business?

How about money?

Writing maintainable code makes your company money

Maintainable code is modifiable code. When would you need to modify code?

Well, most industries are constantly changing.

Snapchat launches an impactful features like stories, then every other social media app finds themselves under pressure to mimic them.

Governments decide that users must be allowed to decline cookies and tracking behavior, and any websites that don't comply will be fined.

Regulators police self-driving vehicle companies, even halting operations until they're compliant.

Any product manager will tell you how critical it is to be able to react quickly in these scenarios. Falling behind the competition can be a dagger.

If you can’t react to a changing environment, you’re at a disadvantage relative to your competitors. If you can, you’re at an advantage.

Reaction time is a competitive advantage. And competitive advantages make your company money.

How can you minimize reaction time?

What is reaction time?

It’s the amount of time it takes for a developer to understand the current state of the code and move it to the desired state.

Any code that currently exists will have to be revisited by a human and modified to move it to the desired state.

You can’t modify something you don’t understand, and that quality of being easily understood is at the very core of what it means to be maintainable.

When variables are named thoughtfully and inputs and outputs are clearly defined, future maintainers will be able to open a file and quickly understand how they can start moving from one state to another.

Thoughtful structure anticipates that the requirements might change. Sometimes in predictable ways, sometimes in wholly unpredictable ways. The bet you make when you write thoughtfully is that you are minimizing the friction for a future maintainer to adapt your code.

When the competition can’t adjust as quickly, it’s not because their current engineers are worse. It’s because all humans require time to understand what they’re looking at and navigate the environment. We can’t change that. But we can make the environment easy or difficult to navigate, and that’s where thoughtful, maintainable code shines. Not when it’s written, but when it’s revisited.

Final takeaway

If you want to build a reputation as someone who consistently anticipates change and enables their team to edge out the competition, write code with this question in mind:

How can I maximize the number of future developers that can be introduced to this code, understand what it does quickly and make a change to it confidently?