Maintainability

Maintainability measures how easily engineers can modify, extend, and debug a system over its lifetime — Lehman's Laws predict that software complexity grows without deliberate investment in maintainability. The four sub-attributes are modularity (independent change units), testability (measurable coverage and fast feedback loops), readability/documentation, and deployability (how easily changes reach production). High maintainability is measured by change lead time (days, not weeks), defect escape rate, and the ratio of time spent on new features vs. firefighting. Teams with strong maintainability practices deploy significantly more frequently with lower change failure rates (per DORA metrics).

Key Points

• Cyclomatic complexity > 10 per function is a maintainability red flag — beyond that, cognitive load exceeds human working memory capacity.
• Test pyramid: 70% unit (fast, isolated), 20% integration (service boundaries), 10% E2E (user journeys); inverting the pyramid creates slow, brittle CI.
• Code coverage is a floor, not a ceiling — 80% coverage with meaningful assertions is more valuable than 100% coverage with trivial tests.
• Dependency inversion: depend on abstractions, not concretions — this makes modules independently testable and swappable (enables strangler fig migrations).
• Documentation as code: OpenAPI/Swagger for APIs, ADRs for decisions, CHANGELOG for history — all version-controlled alongside the code they describe.
• Technical debt has a compound interest analogy — small shortcuts taken under time pressure accumulate into architectural constraints that slow all future work.
• DORA elite performers have change lead times < 1 day, deployment frequency multiple times per day, and change failure rates < 5%.
• Monorepo vs. polyrepo affects maintainability: monorepos simplify cross-cutting changes and dependency management but require sophisticated tooling (Nx, Bazel, Turborepo).