code-simplification

Code Simplification

Simplify code by reducing complexity while preserving exact behavior. The goal is not fewer lines — it's code a new team member would understand faster than the original. Every change must pass that test.

When NOT to use: the code is already clean; you don't yet understand what it does (comprehend first); it's performance-critical and the simpler version would be measurably slower; you're about to rewrite the module entirely (don't polish throwaway code).

The five principles

1. Preserve behavior exactly. Same output for every input, same error behavior, same side effects and ordering, all existing tests pass unmodified. If you're not sure a change preserves behavior, don't make it.
2. Follow project conventions. Simplification means matching the codebase's existing style for imports, error handling, naming, and type annotation depth — not imposing outside preferences. Simplification that breaks project consistency is churn, not simplification.
3. Prefer clarity over cleverness. Explicit code beats compact code whenever the compact version needs a mental pause to parse — e.g. replace a dense nested ternary chain with a small function of if returns; replace a chained reduce doing inline mutation with a named Map built in a loop.
4. Maintain balance — don't over-simplify. Watch for: inlining away a helper that gave a concept a name; merging two simple functions into one complex one; removing an abstraction that exists for extensibility or testability, not complexity; optimizing for line count instead of comprehension.
5. Scope to what changed. Default to simplifying recently modified code. Don't drive-by refactor unrelated code unless asked — it creates diff noise and regression risk.

Process

Step 1 — understand before touching (Chesterton's Fence)

Before changing or removing anything, answer: what is this code's responsibility? What calls it, what does it call? What are its edge cases and error paths? Why might it have been written this way — performance, a platform constraint, history? Check git blame for the original context. If you can't answer these, read more before simplifying.