Maintainable Software (Or, where the code matters)

by

Note: This post is half-baked. I wanted to put together a robust article about all the aspects of maintainable code... but instead just spat out some thoughts, got bored of the topic, and decided to leave it at that. Sorry. Hopefully it still has some meaning even in this state.

The job of an engineer is not to write code. It is to create sustainable software. This includes:

  • Yes, writing code.
  • Making sure that code is easy to follow for people who come after.
  • Documenting how the systems work together, so others can keep it running and build and scale a technical architecture.
  • Communicating with nearby teams.
  • Understanding the directions and needs of the larger business.
  • Keeping their skills up to date, in order to understand when the product needs to evolve based on changes in tech.

This post focuses on the code, but I recommend keeping a holistic view of what an engineer does because all the other aspects of their job should inform the decisions they make as they write that code.

So what is maintainable code? It is code that can be changed for a reasonable level of effort, with a reasonable level of risk.

Sometimes, hopefully most of the time, those changes are enhancements and updates to the software to make it work better for the organazation. But when we talk about how maintainable software is, we also have to deal with the reality that most people are worried about bugs. 

Different coders and teams will produce different quantities of bugs. Finding and fixing those bugs is part of the job. To be clear - all code has bugs. All coders write bugs. Coders vary in how many bugs they write and how fast they deliver new features. You could plot coders on a graph with two axes: speed of code, quantity of bugs. You'd end up with 4 cateogires of coders:

  • Fast Coder, Many bugs - Fine - the faster coding balances the bugfixing time.
  • Slow Coder, Few Bugs - Fine - the slower delivery is balanced by less bugfixing time.
  • Slow Coder, Many Bugs - Not OK. These are the people who are not performing well enough. 
  • Fast Coder, Few Bugs - Great - this is rare, but the ideal. 

There are specific technical approaches to coding that can reduce bugs - type-safe coding practices, re-use of common functions, automated testing and reasonable test coverage. 

Other thoughts, not organized... 

Code should be readable - someone new to a section of code should be able to follow it. They should be able to determine how any given piece of code is run, what it does, what inputs it receives, and its output.

It should not be overly clever - it should use simple syntax and algorithms, and be composed into well-named functions that allow the code to tell is own story of why it exists and what it does. But don’t go overboard on that philosophy...

Some coders never comment their code because they feel that well-written code doesn’t need comments. That is incorrect - well-written code should not need comment to explain what it does, but it absolutely needs comments to explain why it does it, and what product and business needs led to writing the code in the first place.

Some of the easiest codebases I’ve worked in had a few small comments throughout any given code file, but entire books written at the top explaining the larger context of where the code in that file fits into the bigger picture and when and why it was written in the first place. This documentation helps future team members understand and update the code, and is a direct contributor to maintainability. It is part of a holistic approach to being an good engineer.