I read Do best practices really matter? a while ago, in which the author argues that what truly makes code maintainable is a set of qualities.
Here is the list of those qualities:
- readable:
- the code is easy to read and understand
- it's easy to see what it's doing and why
- discoverable:
- it's easy to understand how code is supposed to be used in common cases
- e.g. most users don't want to read through a massive
man curlpage to figure out how to make a simple HTTP request
- predictable:
- it's easy to understand what the code will do in a given situation
- e.g. there are no unexpected side effects
- limited blast radius:
- it's easy to understand the impact of a change
- e.g. if I change this line of code, what else will happen?
- debuggable:
- it's easy to understand what went wrong when something goes wrong
- testable:
- it's easy to write tests for the code
- this includes:
- being able to mock out dependencies
- not having to set up a lot of state to test a small piece of code