Elegant Code

Elegant code = Correctness + Clarity + Minimal complexity + Natural efficiency + Easy change.

Not "shortest" or "cleverest." The solution that makes readers think: "Of course. That's simple, right, and hard to mess up."

Optimization Priority (in order)

Correctness & safety — does what it claims, handles edge cases
Clarity of intent — reader answers "what/why/how" from code itself
Simplicity — minimal concepts that still solve the problem
Changeability — modifications are localized and low-risk
Efficiency — good algorithms; performance from good design, not micro-optimizations

Elegant vs "Smart" Code

Elegant	Smart/Clever
Clarity & solution	Cleverness & brevity
Humans first	Machine first (humans decode)
Low complexity	High complexity
Easy to debug/change	Fragile and opaque
"Of course!"	"Wait… how?"

The Workflow

Use this sequence when writing or refactoring:

1. Clarify the problem

Define inputs, outputs, invariants, constraints, failure modes
Identify postconditions (what must be true after)
List edge cases and "gotchas"

2. Choose simplest correct approach

Pick simplest algorithm/data structure meeting constraints
Prefer fewer concepts over more layers
If adding abstraction, state what complexity it removes

3. Design shape before details

Outline modules/functions and responsibilities
Decide boundaries: pure logic vs side effects (I/O, database, network)

4. Write readable-by-default code

Clear names, small units, straightforward control flow
Make "happy path" obvious; handle errors intentionally

5. Add guardrails

Validation, assertions (where appropriate), tests
Define invalid input handling

6. Refine (remove, simplify, clarify)

Remove duplication, tighten interfaces, reduce nesting
Each unit should read like a single thought

7. Verify against reality

Run tests; benchmark if performance matters
Confirm behavior matches original problem statement

Core Rules

Rule 1 — Preserve intent above everything

Reader must answer: What does this do? Why? What constraints? What can go wrong?

Comments explain why, tradeoffs, constraints—not what code does
If you need comments to explain what, the code is unclear

Rule 2 — Minimize concepts, not lines

Keep distinct "ideas" (types, abstractions, layers, config knobs) minimal.

Prefer one good function over a mini-framework
No "future-proofing" without concrete known need
If abstraction adds indirection without removing complexity, remove it

Rule 3 — Common case simple; edge cases explicit

Happy path easy to follow
Edge cases via early returns, guard clauses, explicit validation
Avoid deep nesting hiding the main story

Rule 4 — Small, cohesive units

One primary responsibility per function/module/class
Group related logic; separate unrelated concerns
If name needs "and" (parseAndSave), it's doing too much

Rule 5 — Explicit data flow over hidden state

Data through parameters and return values, not globals/singletons/mutable shared state
If you can't test without elaborate setup, hidden context exists
If call order matters, make it explicit

Rule 6 — DRY knowledge, not syntax

Unify if two places must change together
Allow small obvious repetition if abstraction is harder to read
Duplicate code sometimes cheaper than leaky abstraction

Rule 7 — Right algorithmic shape

Choose algorithms/data structures appropriate to constraints
Prefer clarity unless profiling demands complexity
Prefer asymptotic wins over micro-optimizations

Rule 8 — Make invalid states unrepresentable

Represent domain constraints in types/structures so illegal combinations are impossible
Validate at boundaries, convert to trusted internal representations

Rule 9 — Local reasoning

Understand a unit without chasing definitions across codebase
Small interfaces, directness over indirection
Configuration close to usage or centralized with clear naming

Rule 10 — Idiomatic but readable

Follow language/project conventions
Don't use obscure tricks only experts recognize
If idiom is compact but unclear, choose clearer form

Micro-Rules

Naming

DO: Names encode intent and domain meaning, not mechanics
DO: Concrete nouns/verbs: calculate_total, is_valid, parse_header
AVOID: Vague names: data, process, handle, doThing, tmp, manager
DO: One concept → one term (consistent vocabulary)

Functions

Short enough for working memory
Inputs/outputs obvious and stable
Side effects clear from name or context
Favor pure functions for core logic
I/O at edges ("functional core, imperative shell")

Control Flow

Avoid deep nesting; use guard clauses
Early exits for invalid conditions
Straightforward over clever

Error Handling

Decide: recover, retry, fallback, or fail fast—then implement consistently
Errors carry enough context to debug
Validate at boundaries
Never swallow errors silently

Dependencies

Depend on stable interfaces, not unstable internals
Minimal and purposeful dependencies
Inject dependencies where it improves testability

Self-Review Checklist

Before finalizing code, verify:

Refactor Decision Rules

Refactor if:

Function/module cannot be summarized in one sentence
Must read twice to trust it
One change requires edits in many unrelated places
Bugs cluster in same area repeatedly
Keep adding special cases ("just one more flag")

Avoid refactoring if:

No tests and behavior unclear (add tests first)
Code stable and rarely changed, improvements purely aesthetic
Near deadline and risk is high (smallest safe improvements only)

Detailed References

Measuring elegance: See references/scorecard.md for the elegance scorecard, objective metrics, and improvement checklist
Anti-patterns: See references/anti-patterns.md for what kills elegance and "smart code" smells
Continuous improvement: See references/continuous-improvement.md for the Continuous Elegance Loop and practices

elegant-code