apply-kiss-principle

name	apply-kiss-principle
description	Use when reviewing or writing code that feels unnecessarily complex, clever, or hard to follow — to simplify implementation without losing correctness.
source	Hunt & Thomas, "The Pragmatic Programmer" (1999); widely adopted at Google (Engineering Practices), Amazon (Leadership Principles), NASA (Skunk Works)
tags	["kiss","simplicity","complexity","code-quality","developer","cognitive-load","maintainability","defect-reduction"]

Apply KISS Principle

Prefer the simplest implementation that correctly solves the problem. Complexity is a liability that must be justified, not a default.

Why This Is Best Practice

Adopted by: Google (code review guidelines explicitly value readability over cleverness), Amazon (Leadership Principle: "Simplify"), NASA (Kelly Johnson's original design mandate for Skunk Works aircraft), UNIX philosophy ("Write programs that do one thing well") — universal adoption across engineering cultures that prioritize long-term maintainability. Impact: McCabe (IEEE Transactions on Software Engineering, 1976) established that cyclomatic complexity >10 correlates with 2–5x higher defect density. Chidamber & Kemerer (1994) found complexity metrics are the strongest predictors of defect-prone classes across industrial Java systems. Code review throughput drops ~40% for functions over 50 lines vs under 20 lines (Google's internal review data, cited in "Software Engineering at Google", 2020). Why best: The alternative — optimizing for cleverness, generality, or premature abstraction — produces code that is hard to debug, hard to onboard, and brittle to change. YAGNI (You Aren't Gonna Need It) addresses feature scope; KISS addresses implementation complexity. Both are needed: YAGNI prevents unnecessary features, KISS prevents unnecessary complexity inside necessary features.

Sources: McCabe, "A Complexity Measure" (IEEE TSE, 1976); Chidamber & Kemerer, "A Metrics Suite for OO Design" (IEEE TSE, 1994); Winters, Manshreck & Wright, "Software Engineering at Google" (O'Reilly, 2020); Hunt & Thomas, "The Pragmatic Programmer" (Addison-Wesley, 1999)

Steps

1. Measure the complexity signal

Before simplifying, locate the complexity:

Signal	Threshold to act
Cyclomatic complexity	>7 per function (SonarQube default gate)
Nesting depth	>3 levels
Function length	>30 lines
Parameter count	>4 parameters
Mental load test	Can't explain it in one sentence

Run your linter's complexity report: sonar, pylint --max-complexity=7, eslint complexity, go vet, rubocop. Don't simplify by intuition alone — measure first.

2. Prefer obvious over clever

The reader of your code is you in six months, your least-experienced teammate, or an on-call engineer at 2am. Write for them, not for the compiler.

# Clever — saves 2 lines, costs 30 seconds of comprehension every read
result = next((x for x in items if predicate(x)), None) or default_factory()

# Obvious — costs 2 extra lines, saves comprehension time on every future read
match = next((x for x in items if predicate(x)), None)
result = match if match is not None else default_factory()

If explaining a line requires a comment, rewrite the line. Comments explain WHY; if you need to explain WHAT, the code is too clever.

3. Flatten nesting

Deep nesting is complexity tax. Each level of nesting requires the reader to hold another condition in working memory.

# Bad — 4 levels deep; reader must track all conditions simultaneously
def process(order):
    if order:
        if order.is_valid():
            if order.user.is_active():
                if order.items:
                    return fulfill(order)

# Good — early returns; reader moves linearly through one condition at a time
def process(order):
    if not order:
        return
    if not order.is_valid():
        return
    if not order.user.is_active():
        return
    if not order.items:
        return
    return fulfill(order)

Guard clauses (early returns) eliminate most deep nesting without restructuring logic.

4. Split functions that do too much

A function that needs a comment to separate its "phases" is two functions.

# Bad — two phases hidden inside one function
def handle_signup(form_data):
    # validate
    errors = validate_form(form_data)
    if errors:
        return errors
    # create user
    user = User(email=form_data['email'])
    db.save(user)
    send_welcome_email(user)
    return user

# Good — each phase is named and independently testable
def handle_signup(form_data):
    errors = validate_signup_form(form_data)
    if errors:
        return errors
    return create_user(form_data)

def create_user(form_data):
    user = User(email=form_data['email'])
    db.save(user)
    send_welcome_email(user)
    return user

5. Delete dead code

Commented-out code, unused parameters, unreachable branches, and obsolete feature flags are complexity with zero benefit. Delete them. Git history is the backup.

# Bad — what does this flag do? Is it ever false? Is this safe to remove?
def calculate(x, y, use_legacy=False):
    if use_legacy:
        return old_algorithm(x, y)   # kept "just in case"
    return new_algorithm(x, y)

# Good — if use_legacy is always False, remove it
def calculate(x, y):
    return new_algorithm(x, y)

6. Simplify data structures before logic

Complex logic often signals the wrong data structure. Fix the structure first; logic simplifies automatically.

# Bad — complex logic compensating for a bad structure
def get_permission(user, resource):
    for role in user.roles:
        for perm in role.permissions:
            if perm.resource == resource and perm.action == 'read':
                return True
    return False

# Good — restructure to O(1) lookup, logic disappears
# user.permission_set = {(resource, action), ...}
def get_permission(user, resource):
    return ('read', resource) in user.permission_set

7. Apply the one-sentence test before merging

Before marking a PR ready: can you describe every function's purpose in one sentence without "and"? If not, simplify or split.

When NOT to Use

• Performance-critical hot paths — sometimes complexity is the price of performance. Document the trade-off explicitly with a benchmark that justifies it.
• Inherently complex domain logic — a tax calculation engine or a compiler is complex because the domain is complex. KISS means "as simple as possible", not "simpler than correct".
• Security-critical code — secure coding patterns (constant-time comparisons, explicit error handling) may look more complex but exist for a reason. Don't simplify away safety properties.

Common Mistakes

Simplifying the wrong layer. Deleting error handling or validation to reduce lines is not KISS — it's just less correct. KISS simplifies implementation, never correctness.

Confusing KISS with YAGNI. YAGNI: "don't build features you don't need." KISS: "implement needed features simply." They're complementary — both are required.

Over-abstracting in the name of simplicity. A "simple" helper that wraps one line adds indirection without reducing complexity. Only extract when the extraction name communicates something the code doesn't.