Despite this being the entirety of some definitions of software quality, in ACRUMEN terms, this is (usually) only the fifth most important aspect, second to last out of six! That’s mainly because the end users (and most other stakeholders) have no clue about it! They aren’t usually allowed to see the code, wouldn’t bother if they could (even most of us geeks don’t bother inspecting the code of the tons of Open Source software we use), and mostly wouldn’t understand it if they saw it, let alone be able (in terms of either skills or time) to evaluate it for Maintainability.
So what does it mean, in ACRUMEN terms, for a piece of software to be Maintainable? The obvious answer is that it’s easy to change. But for who to change? If you’ve been on the same project for five years, maybe its code is easy for you to change, because you know it (and all the underlying technology) so well. But I mean it should be easy to change, with low probablity of error, and low fear of error, even for a novice programmer, who is new to the project.
So how do we achieve that? For better or worse, the vast majority of software engineering advice is aimed squarely at this. Well, not usually the part about fear. So rather than blather on about assorted principles like Single Responsibility, Low Coupling versus High Cohesion, Good Naming, and so on, I’ll tell you how fear plays into it.
Fear is the mind-killer. It makes a developer creep along slowly and carefully, afraid of breaking something, and not noticing (let alone fixing it) until users start complaining. By contrast, if you have a good regression test suite forming a “safety net” to “catch” anything you break, your clear and focused mind will let you proceed at a swift, steady, confident pace. This is just yet another reason to have very high test coverage.
(But if I may stray from maintainability for a moment, there’s another kind of fear we should watch out for, beyond that of simply breaking something. Many workplaces lack psychological safety. In a psychologically-safe workplace, making a mistake usually means you fix it, maybe you get some training if applicable, and if there is a system or process that enabled the mistake too easily, that gets looked at too. In a psychologically-unsafe workplace, making a mistake may mean far more serious negative effects, from ridicule to pay-cuts or even termination. This will of course magnify fear, often to the point where it becomes crippling — and causes the kind of lack of productivity, or sometimes the kind of error, that will subject the person to exactly the feared consequences.)
There are also lots of kinds of tools we can use, like linters, style checkers, object-orientation checkers, and other kinds of static analyzers, that will tell us about assorted maintainability issues. Even just cranking up the warnings on your compiler, interpreter, or whatever, will often reveal a lot of things that are suspicious, and sometimes even bugs. I have often “inherited” a buggy codebase, cranked up the warnings, fixed the causes of warnings, and had bugs disappear.