Complexity

Anything about the structure of a system that makes it hard to understand and modify. Complexity is defined by how the system appears to the people working on it, not by its size or line count.

Why it Matters

Complexity is the primary force that slows software development over a system's lifetime. It is rarely caused by one bad decision; it accumulates from many small ones, so by the time it is painful no single change can remove it. Out of the Tar Pit makes the same case at the level of the whole discipline, naming complexity the root cause of most software problems and mutable state its largest single source.

Signals

• Change amplification: a seemingly simple change requires edits in many places.
• Cognitive load: how much a developer must hold in their head to complete a task.
• Unknown unknowns: it is not obvious what must be changed, or what you must know, to make a change safely. This is the worst symptom because nothing tells you it is there.

Benefits

Treating complexity as the central problem reorients design around understandability. Because it compounds, small consistent reductions pay off disproportionately over time.

Risks

Mistaking complexity for scale or line count; chasing local micro-optimizations while the structural complexity goes untouched; accepting "it's just complex" instead of asking which part is accidental.

Tensions

Some complexity is essential to the problem itself and cannot be removed, only relocated. The goal is to eliminate accidental complexity, not all of it. Reducing complexity is also an investment that competes with short-term delivery pressure.

Examples

A configuration change that forces matching edits across many files is change amplification. A function that only works if called after some other, undocumented setup is an unknown unknown.