Skip to content

Software Quality

Maintainability

Can the next team change it safely?

The codebase stays modifiable: a team can correct, adapt, and extend it without breaking what already works, six months on and after the original authors have left. This is ISO/IEC 25010's Maintainability (ISO/IEC 2011)1. It is the dimension most often missed in early-stage projects and most expensive to repair later.

What goes wrong

  • Test rot. Tests that no longer reflect what the code does; tests that pass because they assert on side effects rather than outcomes; tests that can't be refactored because they're tied to implementation details.
  • Dependency drift. Unpinned, unmaintained, or incompatibility-ridden dependencies. Upgrades and CVE response each become weeks of effort. Build breaks silently when a transitive dep yanks a version.
  • Build-flakiness creep. Tests that fail intermittently; CI pipelines that take 30 minutes; merges that block on irrelevant failures. Engineers start ignoring CI signals.
  • Architectural sediment. Patterns that made sense once layer on top of each other; no one removes the dead code; new features copy nearest neighbor and amplify the drift.
  • Knowledge loss. Original authors leave; understanding of the why leaves with them. Code is rewritten to avoid touching the bits nobody understands.
  • Refactoring becomes impossible. Any meaningful change cascades through hundreds of unrelated tests and modules. The team stops refactoring; quality drops further.

Cheap oracles and signals

Ordered cheapest first.

  1. Build time and test time over a calendar. If CI took 5 minutes last quarter and 25 minutes this quarter, maintainability is eroding.
  2. Test flakiness rate. Percentage of CI runs failing on a retry of the same commit. A single number that tracks erosion directly; flaky tests covers moving it.
  3. Dependency freshness. How many dependencies are more than N months behind upstream. Renovate, Dependabot, and Snyk report this automatically.
  4. Complexity and naming flagged in review. Code review — AI review especially — surfaces the accumulated-complexity and naming drift that motivates refactoring; a rising rate of such findings is a qualitative erosion signal, and review is what replaces folklore-tier smell-catalog dashboards.
  5. Git-history hotspots. Files that change often and are touched by bug-fix commits — the empirical signal for where maintainability is eroding. A git log --stat + grep one-liner is enough for a first pass; git-history hotspots covers the tooling that ranks them.
  6. Type coverage. Under a gradual type system (TypeScript, Python with mypy), the share of the codebase that carries types. A falling share over time signals maintainability erosion.
  7. Mutation testing on the same module quarter over quarter. A mutation-score drop shows the tests have rotted even when coverage hasn't moved.
  8. Bus factor. The number of people who understand each subsystem. Hard to measure; usually known qualitatively. A bus factor of one is a concrete knowledge-loss risk.
  9. Cycle-time for a typical change. Time from idea to deployed. Trended over months. Lengthening cycle time is maintainability rot showing up in productivity numbers.
  10. Developer-experience survey. Self-reported friction: slow feedback, high cognitive load, frequent interruptions. A team perceives erosion before it reaches cycle time, which makes survey responses a leading indicator. Subjective and open to gaming, they flag where to investigate rather than measuring erosion.

What success looks like

  • CI is fast and reliable. Median under 10 minutes; flake rate under 1%.
  • Dependencies are within a small window of upstream. Patch versions caught up automatically; major versions on a calendar.
  • Refactoring happens routinely. On a per-release cadence, not deferred to a later milestone.
  • Tests survive refactors. A behavior-preserving refactor doesn't require rewriting tests. When it does, the tests are coupled to implementation rather than behavior.
  • Mutation score on the critical-business modules is high and stable. A quarterly drop is a signal, not noise.
  • Onboarding a new engineer takes a known number of weeks. Measured, not guessed. Decreasing over time as docs and ADRs improve.
  • The team can still change the oldest code in the system. Not just add features alongside it.

Developer experience

Developer experience (DX) is the colloquial umbrella for two distinct things. The internal sense, a codebase that is good to change, is Maintainability under another name. The product sense, a developer-facing API, SDK, or CLI that is good to use, is Usability with a developer as the user.

The DevEx framework (Noda et al. 2023)2 names three kinds of friction, each addressed by a method this dimension already relies on:

DevEx dimension What reduces it here
Feedback loops (how fast an action answers back) Fast CI and fast tests: median under 10 minutes, flake under 1%
Cognitive load (effort to understand and change) Types, static analysis, dead-code and clone detection, and ADRs that record the why
Flow (uninterrupted focus) Flake reduction and fast local builds: an interruption is usually a broken test or a slow rebuild

Developer experience, productivity, and delivery performance are three scopes, easily conflated. DX is the friction an individual developer feels. Productivity is wider: DX feeds it, but so do organizational factors the codebase cannot touch (bureaucracy, cross-team coordination, slow review, large batch sizes), and the two converge only for a solo developer with no organization around them. SPACE (Forsgren et al. 2021)3 spans that wider space; the DORA keys (Forsgren et al. 2018)4 (deployment frequency, lead time, change-fail rate, recovery time) sit downstream again, a team-level delivery outcome rather than any individual's experience.

So delivery throughput is no proxy for developer experience: a team can post strong DORA numbers on overtime and weak ones on a pleasant codebase. All three are also thin as causal evidence, resting on self-report survey: the DORA work has a peer-reviewed strand (Forsgren et al. 2017)5, but its widely-read form is vendor-published, and the cross-sectional survey design bounds the causal claim either way. Useful as vocabulary and as a leading erosion signal, they stay folklore-tier as proof that an intervention raises productivity.

Referenced by

References

  1. ISO/IEC. 2011. ISO/IEC 25010:2011: Systems and software engineering — SQuaRE — System and software quality models. International Organization for Standardization. https://www.iso.org/standard/35733.html. ↩

  2. Noda, Abi, Margaret-Anne Storey, Nicole Forsgren, and Michaela Greiler. 2023. "DevEx: What Actually Drives Productivity." Queue 21 (2): 35–53. https://doi.org/10.1145/3595878. ↩

  3. Forsgren, Nicole, Margaret-Anne Storey, Chandra Maddila, Thomas Zimmermann, Brian Houck, and Jenna Butler. 2021. "The SPACE of Developer Productivity: There's More to It than You Think." Queue 19 (1): 20–48. https://doi.org/10.1145/3454122.3454124. ↩

  4. Forsgren, Nicole, Jez Humble, and Gene Kim. 2018. Accelerate: The Science of Lean Software and DevOps: Building and Scaling High Performing Technology Organizations. IT Revolution Press. ↩

  5. Forsgren, Nicole, Monica Chiarini Tremblay, Debra VanderMeer, and Jez Humble. 2017. "DORA Platform: DevOps Assessment and Benchmarking." Designing the Digital Transformation (DESRIST 2017), Lecture notes in computer science, vol. 10243: 436–40. https://doi.org/10.1007/978-3-319-59144-5_27. ↩