← Back to principles

Team

Clarity Over Cleverness

Statement

Prefer predictable, discoverable interfaces and APIs. Favour explicitness and readability over clever hacks — code is read far more often than it is written.

What this means in practice

Every piece of code, API, and interface should prioritise being understood quickly by someone who did not write it. Cleverness that saves the author a few keystrokes but costs every future reader minutes of deciphering is a net loss.

  • Code reads like prose where possible — variable names, function names, and module structure tell the story without requiring comments to explain the "trick".

  • APIs and interfaces are discoverable: a developer can explore them through autocompletion, documentation, or reading the signature and understand the expected usage without consulting the source code.

  • Shortcuts, one-liners, and "clever" patterns are avoided when a slightly longer, more explicit version is easier to understand and maintain.

  • Abstractions have clear names that describe what they do, not how they are implemented or what pattern inspired them.

  • Consistency is valued over individual expression — the codebase follows shared conventions so that patterns are recognisable across modules.

  • Comments explain "why", not "what" — if the code needs a comment to explain what it does, it should be rewritten to be self-evident.

Why this matters

Clever code is a maintenance liability.

  • Developers spend the majority of their time reading and understanding existing code, not writing new code. Readability directly impacts velocity.

  • Clever patterns create knowledge silos — only the author (and sometimes not even them, weeks later) understands the intent.

  • Obscure code slows down code reviews, increases review fatigue, and lets bugs slip through because reviewers cannot confidently assess correctness.

  • Unpredictable interfaces lead to misuse, subtle bugs, and defensive coding by consumers who don't trust the API to behave as expected.

  • Clear, consistent code is dramatically easier to onboard new team members onto.

  • Readable code is easier to refactor, extend, and delete — all of which happen far more often than the original writing.

Practices that meet this principle

  • Use descriptive, specific names for variables, functions, and modules — getActiveUsersByRegion() over getData() or process().

  • Prefer explicit control flow (early returns, named conditions, flat logic) over nested ternaries, short-circuit chains, or bitwise tricks.

  • Avoid operator overloading, implicit coercion, and language tricks that rely on obscure runtime behaviour.

  • Write function signatures that are self-documenting: parameter names and types should make the expected usage obvious.

  • Follow established team conventions for naming, file structure, and patterns — consistency across the codebase beats individual preference.

  • When tempted to write a clever one-liner, ask: "Would a new team member understand this in 10 seconds?" If not, expand it.

  • Use linting rules and formatters to enforce consistency automatically rather than relying on manual discipline.

  • In code reviews, flag clever or obscure patterns and suggest clearer alternatives — even if they are longer.

  • Reserve comments for explaining intent, trade-offs, and non-obvious constraints — not for narrating what the code does line by line.

Validation

A project meets this principle when:

  • A developer unfamiliar with a module can read a function and understand its purpose, inputs, and outputs within seconds.

  • Code reviews rarely require the author to explain "what this does" — the code is self-evident.

  • Naming conventions are consistent across the codebase and follow shared team standards.

  • Clever or obscure patterns are rare, and where they exist, they are accompanied by a clear justification comment.

  • New team members can navigate and contribute to the codebase without extended walkthroughs.

  • The team actively prefers readability over brevity in review feedback and coding standards.

Potential blockers

  • Developer culture that rewards cleverness or conciseness as a sign of skill.

  • Inconsistent or absent coding standards, leaving readability to individual judgement.

  • Legacy code with deeply embedded clever patterns that are risky to refactor.

  • Time pressure that encourages "quick and dirty" solutions over clear, well-named alternatives.