Boring Code Is Good Code

2025-07-13 16 min read thoughts
software-engineering philosophy

Boring Code Is Good Code

The cleverest code I've ever written has always been the hardest to maintain. I've learned to be suspicious of clever code.

This isn't a new idea. But it took me years to really internalize it. Maybe writing it down will help someone else get there faster.

The trap

# Look how clever I am!
result = [x for x in (y.process() for y in items if y.valid) if x]

vs:

# Boring, but I can read it in 6 months
result = []
for item in items:
    if item.valid:
        processed = item.process()
        if processed:
            result.append(processed)

The second one is longer. It's also immediately obvious what it does. The first one requires me to parse nested generator expressions and remember the execution order. That's cognitive load I don't want to spend when I'm debugging something at 11pm.

Why cleverness feels good

There's a dopamine hit when you compress something into one line. It feels like you've discovered a secret. You feel smart.

But here's the thing: feeling smart while writing code is a warning sign. The goal isn't to feel smart. The goal is to solve the problem in a way that won't bite you later.

I've met senior engineers who write the most boring, obvious code you've ever seen. And their systems are rock solid. There's a reason.

Signs you're being too clever

  • You feel proud of how compact it is
  • You need to re-read it to understand it
  • The type checker gives up (lots of Any types)
  • You need to explain it in a comment
  • It uses more than two levels of nesting
  • You had to look up how a language feature works to write it

That last one is key. If you're using some obscure language feature that most people don't know, you're creating a landmine for future readers.

The code review perspective

Here's something I didn't appreciate until I started doing a lot of code reviews: boring code is easy to review. Clever code is a nightmare.

When I see a pull request with straightforward, obvious code, I can review it quickly and confidently. I can spot bugs because the logic is clear. I can verify it handles edge cases because I'm not spending my mental energy decoding what the code is even trying to do.

But when someone submits clever code? I have to slow down. I have to trace through the logic multiple times. I second-guess myself. Did I understand that correctly? What happens in this edge case? The review takes 3x longer, and I'm still less confident in my feedback.

This compounds across teams. If your team's codebase is full of clever tricks, every code review becomes slower. Onboarding new people takes longer. Debugging production issues takes longer. You've optimized for the dopamine hit of writing clever code at the expense of everything else your team needs to do.

The best pull requests I've reviewed are almost boring to look at. The code does exactly what the description says it does. No surprises, no hidden complexity. Just straightforward logic that solves the problem.

Real examples from my own code

Bad: Trying to be too functional

users = list(filter(lambda u: u.active, map(lambda u: User(**u), raw_data)))

Good: Just use a loop

users = []
for data in raw_data:
    user = User(**data)
    if user.active:
        users.append(user)

Bad: Over-condensed dictionary comprehension

config = {k: v for k, v in ((x.split('=')[0], x.split('=')[1]) for x in lines) if v}

Good: Readable loop

config = {}
for line in lines:
    key, value = line.split('=')
    if value:
        config[key] = value

The 6-month test

Ask yourself: 'Will I understand this in 6 months?'

If not, simplify it now while you still know what it does. Future you will thank present you.

Or even better: 'Would a junior developer understand this?' If you need to be a language expert to read your code, you've made it too complicated.

When cleverness is okay

Sometimes there's a genuinely better way that happens to be less obvious. That's fine! Just add a comment explaining why:

# Using a set for O(1) lookup since we're checking membership millions of times
valid_ids = set(load_valid_ids())

The comment explains the 'why', which makes the 'what' easier to understand.

Code is read more than written

You write a line of code once. You (and others) will read it dozens of times over its lifetime. Optimizing for reading speed over writing speed is almost always the right tradeoff.

The best code is the code you don't have to think about. It just does what it obviously does. Boring is good.

The performance myth

One objection I hear a lot: "But isn't the clever version more performant?"

Sometimes, yes. Usually, no. And even when it is, it often doesn't matter.

Let me be clear: I'm not saying performance doesn't matter. I'm saying most code isn't a bottleneck, and you should write it clearly first. If profiling shows it's a problem, then optimize. But optimize with benchmarks and comments, not premature cleverness.

I once spent a week optimizing a data processing function. I made it 10x faster using some truly unreadable code. Then I profiled the whole system and realized that function accounted for 0.02% of total runtime. I'd optimized something that saved us 5 milliseconds per day. The code was harder to maintain, and we got basically nothing in return.

Now I follow this rule: write boring code first. Profile if there's a performance issue. Optimize only what matters. And when you do optimize, explain it.

# This looks weird but it's 100x faster for our 10M+ record case
# Benchmark: tests/performance/test_bulk_processing.py
# Previous approach: 45s, this approach: 0.4s
def process_bulk_records(records):
    # ... optimized but documented code ...

Common patterns that should always be boring

Some patterns come up over and over. Here's how I approach them:

Error handling

Bad: Clever exception swallowing

result = (lambda: dangerous_operation())() if safe else None

Good: Explicit error handling

if not safe:
    return None

try:
    result = dangerous_operation()
except SpecificError as e:
    logger.error(f"Operation failed: {e}")
    return None

Data validation

Bad: Compressed validation

valid = all([x for x in [hasattr(obj, a) for a in attrs] if not x] == [])

Good: Clear validation

for required_attr in attrs:
    if not hasattr(obj, required_attr):
        return False
return True

Default values

Bad: Ternary chain

value = x if x else y if y else z if z else default

Good: Sequential checks

value = x
if not value:
    value = y
if not value:
    value = z
if not value:
    value = default

Or even better, use a simple loop:

for candidate in [x, y, z, default]:
    if candidate:
        value = candidate
        break

The team velocity impact

Here's something that surprised me: boring code makes teams ship faster.

When I joined a team that prioritized clever, "elegant" code, our velocity was awful. We'd spend hours in code reviews debating approaches. New features took forever because everyone needed to understand the intricate patterns. Bugs were hard to fix because tracing through the clever code was exhausting.

Then I joined a team with a "boring code" culture. Pull requests flew through review. New engineers contributed meaningful code within weeks, not months. When something broke, we fixed it quickly because the code was obvious.

The clever code team felt smarter. The boring code team shipped more product.

It's counterintuitive, but the "slower" code (more lines, more explicit) leads to faster development. Because you spend less time understanding and more time building.

Think about it this way: if your team spends an extra 30 minutes per day just understanding code before they can modify it, that's 2.5 hours per week per person. On a team of five, that's over 12 hours of wasted time every week. That's more than one full work day, lost to cognitive overhead.

Boring code eliminates that tax. The time you "save" by writing compact clever code gets paid back with interest every single time someone needs to read it.

What about code reuse?

"But if I don't abstract this pattern, I'll repeat myself!"

DRY (Don't Repeat Yourself) is a good principle, but it's not absolute. Sometimes a little repetition is clearer than a complex abstraction.

Bad: Over-abstraction

def process(data, transformer=lambda x: x, filter_fn=lambda x: True,
            aggregator=None, post_process=None):
    items = [transformer(x) for x in data if filter_fn(x)]
    if aggregator:
        items = aggregator(items)
    if post_process:
        items = post_process(items)
    return items

Good: Separate functions for separate use cases

def process_active_users(users):
    active = []
    for user in users:
        if user.is_active:
            active.append(user)
    return active

def process_and_format_users(users):
    formatted = []
    for user in users:
        if user.is_active:
            formatted.append(user.format())
    return formatted

Yes, there's some duplication. But each function is immediately obvious. You don't need to trace through a bunch of optional parameters and lambdas to understand what it does.

The rule I follow: prefer duplication over the wrong abstraction. You can always extract a common pattern later when it's genuinely repeated 3+ times. But a bad abstraction is much harder to undo.

Debugging at 2am

This is the real test: imagine you're oncall, it's 2am, production is down, and you're staring at this code while barely conscious.

Clever code becomes incomprehensible. Boring code is a lifeline.

I've been in this situation more times than I'd like to admit. The code that saves you is the code that's so obvious you can understand it while half-asleep. Clear variable names. Simple logic flow. No surprises.

When you're debugging a production issue, you're already stressed. Your brain isn't working at full capacity. You're thinking about the impact, the angry messages, the user complaints. The last thing you need is to decipher clever code.

Boring code lets you focus on the problem, not on understanding what the code is trying to do. You can trace through it line by line. You can print debug statements easily. You can see exactly where things go wrong.

# When production is down, this is what you want to see:
def process_payment(order):
    if not order.is_valid():
        logger.error(f"Invalid order: {order.id}")
        return False

    payment_result = payment_service.charge(order.total)
    if not payment_result.success:
        logger.error(f"Payment failed: {payment_result.error}")
        return False

    order.mark_paid()
    return True

Not this:

# At 2am, you will hate whoever wrote this
process_payment = lambda o: (ps.charge(o.total).success and o.mark_paid()) \
                            if o.is_valid() else False or logger.error(...)

With the boring version, you can immediately add logging between any step. You can add error handling. You can see the flow. With the clever version, you'd need to refactor it just to debug it.

Teaching opportunities

Boring code is easier to learn from. When a junior developer reads your code, what do they learn?

If your code is full of clever tricks, they learn that programming is about knowing obscure language features. They learn to optimize for feeling smart.

If your code is straightforward and clear, they learn to optimize for clarity. They learn that good code is about solving problems, not showing off.

I've noticed that the most experienced engineers often write the simplest code. They've already proven themselves. They don't need to impress anyone. They just need to solve the problem reliably.

The refactoring test

Boring code is easier to refactor. When requirements change (and they always do), which codebase would you rather modify?

Clever code:
You need to understand the clever bits before you can safely change anything. You might break the elegant pattern. The refactor becomes risky.

Boring code:
You can see exactly what's happening. You can change one part without worrying about ripple effects. The refactor is straightforward.

I've refactored both kinds of codebases. Refactoring boring code is usually smooth. Refactoring clever code often leads to "well, we might as well rewrite this whole thing."

Language-specific gotchas

Different languages tempt you with different cleverness traps:

Python: List comprehensions, lambdas, decorators, metaclasses
JavaScript: Chained promises, implicit returns, destructuring hell
Ruby: Method chaining, monkey patching, DSL magic
Java: Overuse of design patterns, excessive abstraction
Go: Interface gymnastics, channel cleverness

Each language has features that feel powerful but can make code harder to follow. Use them when they genuinely make things clearer, not just because you can.

The counterargument

'But what about elegance? What about beauty in code?'

Truly elegant code is simple and clear. Elegance isn't about being clever; it's about finding the simplest solution that works. The most elegant code I've seen is almost always boring to read. It just... makes sense.

Beauty in code comes from good organization, clear naming, and obvious structure. Not from cramming complex logic into fewer lines.

I've seen "beautiful" code that was absolutely unreadable. And I've seen "boring" code that was genuinely elegant because it made hard problems look easy.

Cleverness isn't elegance. Clarity is.

Real-world case study: The refactor that saved us

Let me share a concrete example from a project I worked on. We had a data processing pipeline that was "beautifully elegant"—lots of function composition, custom operators, and a DSL for defining transformations.

It looked impressive in demos. The original author gave conference talks about it. But it was hell to maintain.

When a new requirement came in (handle nested data structures), we realized the entire elegant system would need to be rewritten. The abstractions were too rigid. We spent three weeks trying to shoehorn the new requirement into the existing clever architecture.

Finally, we gave up and rewrote it with boring, explicit code:

# Old "elegant" version (simplified):
pipeline = (
    DataStream(source)
    .transform(normalize_keys)
    .filter(validate_schema)
    .map(extract_features)
    .reduce(aggregate_results)
)

# New boring version:
def process_data(source):
    results = []
    for record in source:
        # Normalize the keys
        normalized = {}
        for key, value in record.items():
            clean_key = key.lower().strip()
            normalized[clean_key] = value

        # Validate against schema
        if not all(field in normalized for field in required_fields):
            logger.warning(f"Skipping invalid record: {record}")
            continue

        # Extract features
        features = {
            'user_id': normalized['user_id'],
            'action': normalized['action'],
            'timestamp': normalized['timestamp']
        }

        results.append(features)

    return results

The boring version is longer. But when we needed to add nested data support, it took one afternoon instead of three weeks. We could see exactly where to add the new logic. No abstractions to fight against.

The lesson: clever abstractions feel like they'll make future changes easier. But they often make things harder because you're locked into the abstraction's assumptions. Boring code is flexible because it's just... code. You can change it.

The documentation burden

Here's a hidden cost of clever code: documentation.

Boring code often doesn't need much documentation. The code explains itself. You might add a comment here and there, but mostly the code is the documentation.

Clever code requires extensive documentation. You need to explain how it works, why it works that way, what assumptions it makes, what edge cases it handles. And if that documentation gets out of sync with the code (which it will), you're in trouble.

I've seen clever systems with hundreds of lines of documentation trying to explain dozens of lines of code. That's a bad ratio. If your code needs that much explanation, it's too clever.

Compare:

# Clever: needs lots of docs
\"\"\"
Processes records using a lazy evaluation pipeline.

The pipeline uses generators for memory efficiency and allows
composable transformations via the >> operator. Each stage
yields processed items to the next stage.

Example:
    results = process_records(data) >> filter_valid >> transform

Edge cases:
    - Empty input returns empty generator
    - Exceptions in pipeline propagate immediately
    - Pipeline is consumed once (not reusable)
...
\"\"\"
def process_records(records):
    return PipelineGenerator(records)

# Boring: code is self-documenting
def process_records(records):
    \"\"\"Process records, filtering out invalid ones.\"\"\"
    valid_records = []
    for record in records:
        if record.is_valid():
            valid_records.append(record)
    return valid_records

The boring version needs one line of documentation. The clever version needs paragraphs.

When you inherit clever code

What if you're stuck maintaining someone else's clever code? Here's my approach:

  1. Don't rewrite everything: That's tempting but risky. Change things gradually.

  2. Start with pain points: When you need to modify something, simplify it as part of the change.

  3. Add tests first: Before simplifying clever code, add tests to verify behavior. Then simplify confidently.

  4. Document as you learn: When you figure out what clever code does, write a comment. Help the next person.

  5. Set team standards: Agree that new code will be boring. Gradually the codebase will improve.

I once inherited a codebase full of metaclass magic and dynamic attribute generation. I didn't rewrite it all. But every time I touched a file, I simplified one clever bit. After six months, the codebase was dramatically more maintainable, one small change at a time.

How to break the cleverness habit

If you recognize yourself as someone who writes clever code, here's how to change:

  1. Code review yourself: Before submitting a PR, read your code as if someone else wrote it. Do you understand it immediately?

  2. Add the junior dev test: Would someone with 6 months of experience understand this? If not, simplify.

  3. Expand before compressing: Write the explicit version first. Only condense it if it genuinely improves clarity.

  4. Comment your "why": If you need to do something non-obvious, explain why in a comment. If you can't explain why, you probably don't need to do it.

  5. Embrace the loop: Loops are verbose but clear. Don't be afraid of a good old-fashioned for loop.

  6. Watch your pride: If you feel proud of how clever your code is, that's a red flag. Feel proud when your code solves the problem clearly.

  7. Practice explaining: Try explaining your code to a rubber duck or a junior developer. If it takes more than a minute, it's too complex.

  8. Count the concepts: If a single line of code involves more than 2-3 concepts, break it down.

Conclusion: Boring is a feature, not a bug

The best codebases I've worked in were almost boring to read. The logic was obvious. The structure was predictable. There were no surprises.

And that's exactly what made them great. I could find bugs quickly. I could add features confidently. I could onboard new team members easily.

Boring code is productive code. It's maintainable code. It's the kind of code that lets you ship features instead of debugging clever tricks.

So next time you're tempted to write something clever, take a breath. Write the boring version instead. Your future self—and your teammates—will thank you.

The goal isn't to write clever code. The goal is to solve problems so clearly that the code becomes invisible. And there's nothing more powerful than that.

Send a Message