Code Simplification

Simplify code by reducing complexity while preserving exact behavior. The goal is code that is easier to read, understand, modify, and debug.

When to Use

• After a feature is working and tests pass, but the implementation feels heavier than it needs to be
• During code review when readability or complexity issues are flagged
• When you encounter deeply nested logic, long functions, or unclear names
• When refactoring code written under time pressure

The Five Principles

1. Preserve Behavior Exactly

Don't change what the code does — only how it expresses it.

ASK BEFORE EVERY CHANGE:
→ Does this produce the same output for every input?
→ Does this maintain the same error behavior?
→ Does this preserve the same side effects and ordering?
→ Do all existing tests still pass without modification?

2. Follow Project Conventions

Simplification means making code more consistent with the codebase, not imposing external preferences.

3. Prefer Clarity Over Cleverness

// UNCLEAR: Dense ternary chain
const label = isNew ? 'New' : isUpdated ? 'Updated' : isArchived ? 'Archived' : 'Active';

// CLEAR: Readable mapping
function getStatusLabel(item: Item): string {
  if (item.isNew) return 'New';
  if (item.isUpdated) return 'Updated';
  if (item.isArchived) return 'Archived';
  return 'Active';
}

4. Maintain Balance

Watch for over-simplification traps:

• Inlining too aggressively
• Combining unrelated logic
• Removing "unnecessary" abstraction
• Optimizing for line count

5. Scope to What Changed

Default to simplifying recently modified code. Avoid drive-by refactors of unrelated code.

The Simplification Process

Step 1: Understand Before Touching (Chesterton's Fence)

Before changing anything, understand why it exists:

BEFORE SIMPLIFYING, ANSWER:
- What is this code's responsibility?
- What calls it? What does it call?
- What are the edge cases and error paths?
- Are there tests that define the expected behavior?
- Why might it have been written this way?

Step 2: Identify Simplification Opportunities

Structural complexity:

Pattern	Signal	Simplification
Deep nesting (3+ levels)	Hard to follow control flow	Extract into guard clauses
Long functions (50+ lines)	Multiple responsibilities	Split into focused functions
Nested ternaries	Requires mental stack	Replace with if/else chains
Boolean parameter flags	doThing(true, false, true)	Replace with options objects
Repeated conditionals	Same if check in multiple places	Extract to predicate function

Naming and readability:

Pattern	Signal	Simplification
Generic names	data, result, temp	Rename to describe content
Misleading names	Function named get that mutates	Rename to reflect behavior
Comments explaining "what"	// increment counter	Delete the comment
Comments explaining "why"	// Retry because API is flaky	Keep these — they carry intent

Redundancy:

Pattern	Signal	Simplification
Duplicated logic	Same 5+ lines in multiple places	Extract to shared function
Dead code	Unreachable branches, unused variables	Remove
Unnecessary abstractions	Wrapper that adds no value	Inline the wrapper
Over-engineered patterns	Factory-for-a-factory	Replace with simple approach

Step 3: Apply Changes Incrementally

Make one simplification at a time. Run tests after each change.

Step 4: Verify the Result

COMPARE BEFORE AND AFTER:
- Is the simplified version genuinely easier to understand?
- Did you introduce any new patterns inconsistent with the codebase?
- Is the diff clean and reviewable?
- Would a teammate approve this change?

Language-Specific Guidance

TypeScript / JavaScript

// SIMPLIFY: Unnecessary async wrapper
// Before
async function getUser(id: string): Promise<User> {
  return await userService.findById(id);
}
// After
function getUser(id: string): Promise<User> {
  return userService.findById(id);
}

// SIMPLIFY: Verbose conditional assignment
// Before
let displayName: string;
if (user.nickname) {
  displayName = user.nickname;
} else {
  displayName = user.fullName;
}
// After
const displayName = user.nickname || user.fullName;

// SIMPLIFY: Manual array building
// Before
const activeUsers: User[] = [];
for (const user of users) {
  if (user.isActive) {
    activeUsers.push(user);
  }
}
// After
const activeUsers = users.filter((user) => user.isActive);

Verification

After completing a simplification pass:

• All existing tests pass without modification
• Build succeeds with no new warnings
• Each simplification is a reviewable, incremental change
• Simplified code follows project conventions
• No error handling was removed or weakened
• No dead code was left behind
• A teammate would approve the change as a net improvement