KISS in software design and review

Clever code wins the diff. Simple code wins the on-call. KISS is the reminder to optimize for the second audience.

Keep it simple, stupid.

That line is usually traced to Kelly Johnson and the Lockheed Skunk Works habit of insisting engineers could fix a plane in the field with everyday tools (Wikipedia’s article on the KISS principle summarizes the folklore). In software we borrow it as a design rule. Prefer the shape a teammate can read, change, and delete without a map.

KISS is not a ban on abstraction. It is a check on cleverness, the kind that hides state, spreads invariants across layers, or makes the happy path depend on tribal knowledge. When two designs meet the same requirements and failure modes, the one with fewer concepts and fewer places truth can drift is the keeper.

Start from the behavior you owe users, then add structure until that behavior is credible. Stop when the next layer is optional. Frameworks, indirection, and generic hooks earn their rent when they remove repeated risk (bugs, drift, policy you already promised). They do not earn it when they postpone a decision you could make in one module today.

Occam’s razor is the close cousin here, but KISS is blunter.

In review, treat complexity as a claim that needs evidence, the same way you would treat a perf win or a security fix.

Ask whether the PR introduces a new concept the rest of the system must learn. Names, files, and lifecycle rules all count. If the answer is yes, the author should be able to point at the pain the concept removes. Generic extensibility for a single call site is a smell.

Prefer reviews that shrink diffs when the requirement allows. Smaller APIs, fewer flags, fewer configuration surfaces. If the author cannot explain the change in one paragraph aloud, the reader will not survive the merge either.

Compliment work that deletes code. Removal is often the highest-fidelity simplicity you can ship.

Some problems are inherently messy (billing, permissions, migration paths). KISS does not mean pretend the mess is not there. It means contain it. Put the hard rules behind one boundary, document the invariants you chose, and keep the callers dumb.

When the team already owes a capability (latency, compliance, isolation), simplicity is whatever layout makes that obligation testable. Necessity has entered the room. The principle stops arguing against the work. It argues against extra ceremony on top of it.

The goal is not minimal line count. It is a system where the default path is obvious, the sharp edges are labeled, and the next person does not need your walkthrough to ship a fix.