| name | elegant-code |
| description | Language-agnostic rulebook for producing, reviewing, and improving elegant code. Use when writing new code, refactoring existing code, reviewing code quality, or when user asks for "elegant", "clean", "maintainable", or "well-structured" code. Applies to any programming language or framework. |
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
