← Patterns

Maintainability Over Comprehension

Pattern · engineering-culture

Core Concept

Understanding a codebase’s overall design is not a prerequisite to contributing to it. The hallmark of a great codebase is one that allows change without needing to hold the whole thing in your head. If you find yourself trying to keep a ton of different things in your cognitive space while changing code to ship a feature, that’s a thread worth pulling on.

Compared to vanity/aesthetic concerns, making code easy to change is a much better goal.

The Investment Paradox

Dave perpetually underestimates how much value and velocity you can get out of investing directly in the maintainability of your codebase. Next time you find yourself having to hold too much in your head while trying to make a change, pull on that thread and pull on it hard.

This connects to the AI era: AI-ready codebases are maintainable codebases. LLMs refactor healthy code 30% more reliably (Tornhill). The investment in maintainability pays dividends both for humans and AI agents.

The Quality Test

Instead of asking “is this code beautiful?” ask:

• Can a new person (or AI) make a change without understanding the whole system?
• When you change one thing, do other things break unexpectedly?
• Is the blast radius of any change predictable?

Related Patterns

• AI-Ready Engineering — maintainable code is AI-ready code
• Gall’s Law — complex systems that work evolved from simple ones; maintainability is what allows evolution
• Lehman’s Laws — software complexity increases unless actively reduced; maintainability is the active reduction

Cross-References