KISS Principle
debt(d7/e5/b7/t5)
Closest to 'only careful code review or runtime testing' (d7). The detection_hints state automated detection is 'no' and the tool listed (phpstan) cannot reliably flag over-engineering or unnecessary abstraction — it catches type and static errors, not design violations. Identifying KISS violations requires human judgment in code review; the pattern (factory factory factories, excessive abstraction layers) is invisible to most automated tooling.
Closest to 'touches multiple files / significant refactor in one component' (e5). The quick_fix frames it as a reflective question rather than a mechanical swap. Common mistakes involve accumulated abstraction layers (design patterns, extra indirection, over-engineered error handling) that, once in place, typically require refactoring across multiple related files or components to remove — not a one-liner, but not necessarily a full architectural rework.
Closest to 'strong gravitational pull' (b7). KISS violations tend to be load-bearing: an over-engineered abstraction layer or unnecessary design pattern shapes every subsequent feature built on top of it. Because it applies across web, cli, and queue-worker contexts, the accumulated complexity tax affects many work streams. Every new contributor must navigate the unnecessary complexity, and removing it requires cross-cutting effort.
Closest to 'notable trap — a documented gotcha most devs eventually learn' (t5). The misconception field directly identifies the trap: developers frequently equate KISS with 'avoid all abstractions and patterns,' when KISS actually permits well-placed patterns that genuinely reduce complexity. This is a well-documented misreading that causes both under-engineering (stripping useful patterns) and over-engineering (misapplying 'best practices') — a real but learnable gotcha.
Also Known As
TL;DR
Explanation
KISS (variously: Keep It Simple, Stupid; Keep It Short and Simple) advocates simplicity as a primary design goal. Unnecessary complexity is the root cause of many bugs and maintenance burdens — complex code is harder to understand, harder to test, and harder to change. KISS is not an argument against abstraction but against incidental complexity: solve the essential complexity of the problem without adding accidental complexity through clever patterns, premature optimisation, or speculative architecture.
Common Misconception
Why It Matters
Common Mistakes
- Implementing a design pattern because it is a 'best practice' when a simple function or array would solve the problem.
- Adding abstraction layers before there is evidence they are needed — YAGNI is KISS's sibling.
- Over-engineering error handling: try/catch around every single line rather than at appropriate boundaries.
- Mistaking familiarity with simplicity — a pattern you know well may still be overkill for the problem.
Avoid When
- Using simplicity as an excuse to skip error handling, logging, or security controls — simple code still needs to be correct.
- Conflating simple with familiar — a recursive solution may be simpler than an imperative one even if it looks less familiar.
- Oversimplifying until the code no longer handles real edge cases — simplicity must not sacrifice correctness.
When To Use
- When reviewing a solution that has grown complex — ask whether a simpler approach solves the same problem.
- Architecture decisions — prefer the simplest design that meets the requirements, not the most flexible one imaginable.
- Code review — flag unnecessary abstraction, premature generalisation, and clever tricks that obscure intent.
- Teaching and onboarding — simple, readable code is self-documenting and lowers the learning curve.
Code Examples
// Over-engineered: AbstractStrategyFactoryBuilderProvider
class UserSorterStrategyFactoryBuilderProvider {
public function buildStrategyFactory(): UserSorterStrategyFactory { ... }
}// KISS: just a function
function sortUsersByName(array $users): array {
usort($users, fn($a, $b) => strcmp($a->name, $b->name));
return $users;
}