“Building Maintainable Software” — A Very Short Review
Maintenance is what keeps everything going. It’s what keeps life going. But so much of doing maintenance is tiresome. Brush the damn teeth, change the damn oil. They are unrewarding chores — repetitive, boring, often frustrating, and endless. Since that part of maintenance is a pain, we shirk it, defer it, fail to budget time or money for it, let it drop to the bottom of the priority list. That’s easy to do because the necessity of maintenance accumulates invisibly and gradually. Then suddenly one day the thing breaks, the system falters, and everything stops in a turmoil of disruption, expense, and blame.
The apparent paradox is profound: Maintenance is absolutely necessary and maintenance is optional.
This lean book offers an interesting model to quantify software maintainability using a Java codebase as example. The model is built on ten (10) generally accepted principles and SIG’s (the author’s parent organization) take on each to rank best-of-the-breed software. The principles, simplified here, and thresholds to be “4 stars” are, roughly,
1. Short methods — at least half the methods to be 15 lines or less.
2. Methods with shorter “branching factor” (or Cyclomatic Complexity) — at least 75% with 5 or less.
3. Code is not duplicated a lot — at least 95% code is “non-redundant” (i.e., not copied elsewhere)
4. Methods have short “interfaces” (i.e., input params) — at least 85% methods have at most 2 inputs.
5. Modules (i.e., classes) are loosely coupled — at most 20% of classes have >10 incoming calls (fan in) aggregated over its methods.
6. Components (e.g., packages) are loosely coupled — no more than 15% code residing in modules with incoming dependency.
7. Components are balanced in size and numbers — equivalent of “Gini Coefficient” — the metric used to compare income equality, 0.0 being perfectly egalitarian society, 1.0 being perfectly inequal — ideally, about 9 components with inequality coefficient being 0.7
8. Small Codebase — equivalent to 20 person-years to completely rebuild. This equates to about 175,000 lines of code in Java.
9. Testability — higher automation in tests — interestingly, measured with combination of #2, #6 and #8 above — not with coverage. Hypothesis here is smaller codebase where packages are loosely coupled and methods/functions are not complex is easy to automate with tests. I agree with this — writing tests or automating tests is a 2nd order problem (much easier to fix) if the 1st order (code is testable) problem is solved. If not, the investment in automating is super-linear and ROI is low/negative.
10. Clean Code — generally, without obvious “smells”, e.g., good comments, no dead code (something that is not used!), no long names, no badly/unhandled exceptions.
This is a unique take on something we all grapple in real life. I really liked some insights — especially, earlier chapters illustrated, say, how to use “value object” to reduce a method’s signature; or use fluent interface style in constructors to make code readable etc. I wholeheartedly agree with the author that measuring testability != measuring tests. That, from experience, has been a foundational flaw of most very senior level technology leadership. If we blindly try to fix lack of test coverage in a legacy codebase without evaluating its “testability” (e.g., volume, coupling and structure), it will be as if we are asking a senior member of society who has never lifted weight to deadlift 2x his bodyweight in 2 months! It will not only cause wasted efforts, but could do serious harm as well.
Like all models, squint at the specific model but rather at the framework of code maintainability to get most value from this delightfully short book.
That said, important things with nuance are always observable but not readily measurable. Apart from noise and jitter associated with measuring a 10 year old codebase contributed by 400 engineers, maintainability is inherently a technology dimension. The other two principal axes are business- did/are we make a conscious trade-off, say, for growth; and people- most leaders are inherent optimists and they “frequently resent the need for maintenance and tend to resist doing it, instead preferring to live in the world of ideals rather than the drudgery of constant tasks.”
The eleventh, and most important, pattern would be “To influence the real-life need of maintainability”. But that is the essential key to successfully leading irrespective — either to build or to maintain!
