Obvious Code

Code is obvious when a reader can understand what it does and why with little effort, forming a correct mental model on the first read and rarely being surprised. Nonobvious code is the enemy.

Why it Matters

Code is read far more often than it is written, and obviousness is a property judged by the reader, not the author. Nonobvious code raises cognitive load and breeds unknown unknowns, the two most damaging symptoms of complexity.

Signals

• Readers repeatedly ask "how does this work?" or guess wrong.
• Obscurers: generic or vague names, inconsistent conventions, hidden dependencies, behavior driven by state that is far from where it is used.

Benefits

Lower cognitive load, faster onboarding, fewer bugs from misunderstanding. Obviousness compounds with consistency: the more predictable the codebase, the less any single piece needs to be studied.

Risks

"Obvious to me" is not obviousness; the author is the worst judge. Cleverness, premature abstraction, and excessive indirection make code shorter but less obvious.

Tensions

Sometimes conflicts with conciseness or with language features (some uses of generics, operator overloading, event-driven control flow) that save keystrokes while obscuring control and data flow. Favor the reader.

Examples

Consistent naming and conventions let a reader predict behavior without checking. Control flow that jumps through events or callbacks with no obvious sequence forces the reader to reconstruct the order, making it nonobvious.