Software complexity is anything that makes a system harder to understand, modify, or maintain. It accumulates gradually as evolving requirements, rushed decisions, inconsistent practices, outdated technology, and external dependencies reshape the codebase. Simplicity does not remove necessary difficulty; it refines complexity into a clearer, more maintainable form. section 1.1.2 section 3.1.1
Distinguish the kinds of complexity and the signals used to manage them:
- Essential complexity comes from the problem domain and must be managed rather than removed. section 3.3
- Accidental complexity comes from poor design, outdated code, or overengineering and should usually be removed through refactoring. section 3.3
- Cyclomatic complexity counts decision points and linearly independent paths, while cognitive complexity highlights flow-breaking structures and nested logic that burden readability. section 3.3
- Six practical levers—Prevent, Organize, Reduce, Hide, Investigate, and Endure—address complexity through team habits, structure, code clarity, maintenance, and containment. section 3.2
How complexity enters a codebase
A deadline may favor the fastest implementation over the most maintainable one. Later, hypothetical future requirements encourage overengineering, inconsistent team decisions multiply solutions to the same problem, and changing requirements break the original design. The resulting complexity may be reduced, isolated behind clear boundaries, or documented when removal is impractical. section 3.1.1 section 3.3
Figure 3.3 The six levers of code simplicity
Use the six-lever framework to connect complexity signals with practical interventions and code-review guidance. section 3.2
