code-simplification

Code Simplification

Overview

Reduce complexity while preserving exact behavior. The goal is code that a new engineer can read and understand without asking the author questions. Simplification is not optimization — do not change performance characteristics unless that is the explicit goal.

When to Use

• Code works but is harder to read than it should be
• A function is doing more than one thing
• Nested conditionals make the control flow hard to follow
• Variable names are generic (data, result, temp)
• The same logic appears in multiple places
• A reviewer needed to ask what the code does

When NOT to use: Code that is intentionally complex for performance reasons (document with a comment instead of simplifying).

The Chesterton's Fence Rule

"Don't remove a fence you don't understand."

Before simplifying any code, answer: why was it written this way? If you can't answer that, you risk removing a safeguard. Read the git history, grep for related tests, and understand the intent before changing anything.

The Simplification Process

Step 1: Understand Before Touching

• Read the function end-to-end
• Read its callers — what do they expect?
• Read its tests — what behavior is verified?
• Check git history: git log -p -- path/to/file.py
• Do not change anything yet

Step 2: Cover First

If the code lacks tests, add tests before simplifying. You need a safety net:

def test_generate_skill_name_sanitizes_input():
    assert generate_skill_name("my repo") == "my-repo"
    assert generate_skill_name("My Repo!") == "my-repo"
    assert generate_skill_name("  spaces  ") == "spaces"

Run them, confirm they pass. Now you can simplify safely.

Step 3: Apply Simplifications Incrementally

Apply one simplification at a time, running tests after each:

Deep Nesting → Guard Clauses

# BAD: Pyramid of doom
def process_skill(skill):
    if skill is not None:
        if skill.get("name"):
            if len(skill["name"]) > 0:
                return skill["name"].lower()
        return None
    return None

# GOOD: Guard clauses
def process_skill(skill):
    if not skill:
        return None
    if not skill.get("name"):
        return None
    return skill["name"].lower()