alexandru/simplify

Code Simplification

Source. Adapted.

Overview

Simplify code by reducing complexity while preserving exact behavior. The goal is not fewer lines — it's code that is easier to read, understand, modify, and debug. Every simplification must pass a simple test: "Would a new team member understand this faster than the original?"

When to Use

• After a feature is working and tests pass, but the implementation feels heavier than it needs to be
• During code review when readability or complexity issues are flagged
• When you encounter deeply nested logic, long functions, or unclear names
• When refactoring code written under time pressure
• When consolidating related logic scattered across files
• After merging changes that introduced duplication or inconsistency

When NOT to use:

• Code is already clean and readable — don't simplify for the sake of it
• You don't understand what the code does yet — comprehend before you simplify
• The code is performance-critical and the "simpler" version would be measurably slower
• You're about to rewrite the module entirely — simplifying throwaway code wastes effort

The Five Principles

1. Preserve Behavior Exactly

Don't change what the code does — only how it expresses it. All inputs, outputs, side effects, error behavior, and edge cases must remain identical. If you're not sure a simplification preserves behavior, don't make it.

ASK BEFORE EVERY CHANGE:
→ Does this produce the same output for every input?
→ Does this maintain the same error behavior?
→ Does this preserve the same side effects and ordering?
→ Do all existing tests still pass without modification?

2. Follow Project Conventions

Simplification means making code more consistent with the codebase, not imposing external preferences. Before simplifying:

1. Read AGENTS.md / CLAUDE.md / project conventions
2. Study how neighboring code handles similar patterns
3. Match the project's style for:
   - Import ordering and module system
   - Function declaration style
   - Naming conventions
   - Error handling patterns
   - Type annotation depth

Simplification that breaks project consistency is not simplification — it's churn.

3. Prefer Clarity Over Cleverness

Explicit code is better than compact code when the compact version requires a mental pause to parse.

Apply the principle of least power. When two designs express the same behavior, prefer the one that uses less powerful abstractions: plain functions over classes, immutable records over mutable state, data over behavior. A function is easier to read, test, and compose than a class; a record is easier to inspect than an object with hidden state. This is a tiebreaker, not a mandate — defer to project conventions (Principle 2) and keep abstractions that protect API stability, testability, or real extension points (Principle 4).

4. Maintain Balance

Simplification has a failure mode: over-simplification. Watch for these traps:

• Inlining too aggressively — removing a helper that gave a concept a name makes the call site harder to read
• Combining unrelated logic — two simple functions merged into one complex function is not simpler
• Removing "unnecessary" abstraction — some abstractions exist for extensibility or testability, not complexity
• Optimizing for line count — fewer lines is not the goal; easier comprehension is

5. Scope to What Changed

Default to simplifying recently modified code. Avoid drive-by refactors of unrelated code unless explicitly asked to broaden scope. Unscoped simplification creates noise in diffs and risks unintended regressions.

The Simplification Process

Step 1: Understand Before Touching (Chesterton's Fence)

Before changing or removing anything, understand why it exists. This is Chesterton's Fence: if you see a fence across a road and don't understand why it's there, don't tear it down. First understand the reason, then decide if the reason still applies.

BEFORE SIMPLIFYING, ANSWER:
- What is this code's responsibility?
- What calls it? What does it call?
- What are the edge cases and error paths?
- Are there tests that define the expected behavior?
- Why might it have been written this way? (Performance? Platform constraint? Historical reason?)
- Check git blame: what was the original context for this code?

If you can't answer these, you're not ready to simplify. Read more context first.

Step 2: Identify Simplification Opportunities

Scan for these signals — each one is a concrete pattern, not a vague smell:

• Deep nesting (3+ levels) — guard clauses, early returns, or small helpers can flatten the flow
• Long functions (50+ lines) — split by responsibility, not by arbitrary line count
• Nested ternaries — replace with readable branching
• Boolean parameter flags — replace with options objects or separate functions
• Repeated conditionals — extract to a well-named predicate function
• Generic or abbreviated names — rename to describe the content
• Misleading names — rename to reflect actual behavior
• Comments explaining "what" — delete; the code is clear enough. Keep comments that explain "why"
• Duplicated logic — extract the repeated decision or transformation once
• Dead code — remove unused branches, parameters, and helpers (after confirming they're truly dead)
• Unnecessary abstractions — remove wrappers that add indirection without value
• Over-abstracted patterns — interface with one implementation, class that could be a function, typeclass with one instance — replace with the simplest construct that expresses the behavior
• Redundant type assertions — remove casts to types that are already inferred

For detailed signal tables, see simplification patterns.

Step 3: Apply Changes Incrementally

Make one simplification at a time. Run tests after each change. Submit refactoring changes separately from feature or bug fix changes. A PR that refactors and adds a feature is two PRs — split them.

FOR EACH SIMPLIFICATION:
1. Make the change
2. Run the test suite
3. If tests pass → commit (or continue to next simplification)
4. If tests fail → revert and reconsider

Avoid batching multiple simplifications into a single untested change. If something breaks, you need to know which simplification caused it.

The Rule of 500: If a refactoring would touch more than 500 lines, invest in automation (codemods, sed scripts, AST transforms) rather than making the changes by hand. Manual edits at that scale are error-prone and exhausting to review.

Step 4: Verify the Result

After all simplifications, step back and evaluate the whole:

COMPARE BEFORE AND AFTER:
- Is the simplified version genuinely easier to understand?
- Did you introduce any new patterns inconsistent with the codebase?
- Is the diff clean and reviewable?
- Would a teammate approve this change?

If the "simplified" version is harder to understand or review, revert. Not every simplification attempt succeeds.

Verification

After completing a simplification pass:

• [ ] All existing tests pass without modification
• [ ] Build succeeds with no new warnings
• [ ] Linter/formatter passes (no style regressions)
• [ ] Each simplification is a reviewable, incremental change
• [ ] The diff is clean — no unrelated changes mixed in
• [ ] Simplified code follows project conventions (checked against AGENTS.md / CLAUDE.md or equivalent)
• [ ] No error handling was removed or weakened
• [ ] No dead code was left behind (unused imports, unreachable branches)
• [ ] A teammate or review agent would approve the change as a net improvement

References

• simplification patterns — signal tables, common rationalizations, red flags, and test prompts