# Maintainability 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)[^isoiec25010_2011]. 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](https://quality.stereobooster.com/flaky-tests.md) covers moving it. 3. **Dependency freshness.** How many dependencies are more than N months behind upstream. [Renovate](https://docs.renovatebot.com/), [Dependabot](https://github.com/dependabot/dependabot-core), and Snyk report this automatically. 4. **Complexity and naming flagged in review.** [Code review](https://quality.stereobooster.com/code-review.md) — 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](https://quality.stereobooster.com/design-folklore.md). 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](https://quality.stereobooster.com/git-hotspots.md) covers the tooling that ranks them. 6. **Type coverage.** Under a gradual type system (TypeScript, Python with [mypy](https://github.com/python/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](https://quality.stereobooster.com/quality-dimensions.md#usability) with a developer as the user. The DevEx framework (Noda et al. 2023)[^noda2023] 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](https://quality.stereobooster.com/types.md), [static analysis](https://quality.stereobooster.com/static-analysis.md), [dead-code](https://quality.stereobooster.com/dead-code-detection.md) and [clone detection](https://quality.stereobooster.com/clone-detection.md), and [ADRs](https://quality.stereobooster.com/adrs.md) 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)[^forsgren2021] spans that wider space; the DORA keys (Forsgren et al. 2018)[^forsgren2018] (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)[^forsgren2017], 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 - [Quality dimensions](https://quality.stereobooster.com/quality-dimensions.md) · Quality dimensions - [The test suite as an object](https://quality.stereobooster.com/test-suite.md) · Methods - [Agent experience](https://quality.stereobooster.com/ai-agent-experience.md) · AI - [Choosing methods](https://quality.stereobooster.com/choosing.md) · Overview ## References [^isoiec25010_2011]: ISO/IEC. 2011. *[ISO/IEC 25010:2011: Systems and software engineering — SQuaRE — System and software quality models](https://www.iso.org/standard/35733.html)*. International Organization for Standardization. . [^noda2023]: Noda, Abi, Margaret-Anne Storey, Nicole Forsgren, and Michaela Greiler. 2023. "[DevEx: What Actually Drives Productivity](https://www.michaelagreiler.com/wp-content/uploads/2024/06/DevEx-WhatDrivesProductivity.pdf)." *Queue* 21 (2): 35–53. . [^forsgren2021]: 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](https://queue.acm.org/detail.cfm?id=3454124)." *Queue* 19 (1): 20–48. . [^forsgren2018]: 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. [^forsgren2017]: Forsgren, Nicole, Monica Chiarini Tremblay, Debra VanderMeer, and Jez Humble. 2017. "[DORA Platform: DevOps Assessment and Benchmarking](https://www.researchgate.net/publication/318018911_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](https://doi.org/10.1007/978-3-319-59144-5\_27). ## Acronyms - ADR — architecture decision record - SPACE — Satisfaction, Performance, Activity, Communication, Efficiency (developer-productivity framework)