simple-design

Simple Design

Purpose

Keep code within the limits of human working memory. Complexity is not measured by line count but by how many things you must hold in your head at once to be confident a change is correct.

When to Use

• A function or module has become hard to reason about.
• Reviewers keep missing defects in a particular file.
• A change in one place keeps breaking something in another.
• Deciding whether an abstraction is worth its indirection.

Capabilities

• Cyclomatic and cognitive complexity measurement and reduction.
• Dependency counting and reduction at the function and module level.
• Encapsulation: making the number of things a caller must know as small as possible.
• Guard-clause restructuring to flatten nesting.
• Identifying the abstraction that removes the most conditionals.

Inputs

• The code and the reason it is hard: too long, too nested, too many dependencies, too many states.
• Complexity metrics from a linter, if available.

Outputs

• Functions that fit on a screen and have one reason to exist.
• Modules with a small public surface and a large private interior.
• A stated limit the team agrees to enforce.

Workflow

1. Measure, do not guess — Cyclomatic complexity per function, dependency count per module. Find the actual outliers.
2. Flatten first — Replace nested conditionals with guard clauses. Most deeply nested code is shallow logic wearing a costume.
3. Reduce the inputs — A function taking seven parameters is describing a missing type. Introduce it.
4. Shrink the public surface — Everything not needed by a caller becomes private. A module with three public functions is comprehensible regardless of its size.
5. Delete — The simplest code is the code that is not there. Remove unused options, flags, and abstractions built for a future that did not arrive.
6. Set the ceiling — Agree a limit (for example, cyclomatic complexity of 7) and enforce it in the linter, so this does not have to happen again.