Stop Writing Clever Code

1 November 2024 · 2 min read · Syed Omar Faruk Towaha

I once wrote a single line of Python that parsed a config file, filtered it, sorted it and built a lookup table. It used a nested comprehension, a lambda, functools.reduce and the walrus operator. I was very proud. I showed it to a colleague, who looked at it for a long time and then asked, kindly, "Are you okay?"

He was right. Clever code is a gift you give yourself and a bill you send to everyone else.

Code is read far more than it's written

Lifetime of a line of code — Rough, but the shape is right: writing is the cheap part.

A line of code is written once, then read during reviews, during debugging, during refactors and by every new team member trying to understand the system. Optimising for the writing moment is like designing a house to be pleasant to build rather than to live in.

A before and after

Clever:

active = {u.id: u for u in sorted((u for u in users if u.active and (d := u.last_seen) and d > cutoff), key=lambda u: u.name)}

Boring, and better:

def is_recently_active(user, cutoff):
    return user.active and user.last_seen is not None and user.last_seen > cutoff

recent_users = [u for u in users if is_recently_active(u, cutoff)]
recent_users.sort(key=lambda u: u.name)
active_by_id = {u.id: u for u in recent_users}

It's longer. It's also obvious. Each line does one thing, the condition has a name that explains why, and when a bug appears in the filtering you can put a breakpoint on exactly the line you care about.

Signs your code is too clever

You needed a comment to explain what it does, not why.
It uses a language feature your teammates have never seen, for no performance reason.
You'd be nervous to change it.
It's described in review as "interesting."

When clever is fine

Sometimes you genuinely need the tricky version: a hot loop that runs a billion times, a bit-twiddling hash function, a carefully tuned SQL query. That's fine. Put it in a well-named function, write a comment explaining why the simple version wasn't good enough, add a benchmark and a test, and keep it small. Clever code belongs in a cage with a sign on it, not loose in the codebase.

The real flex

The developers I admire most write code that looks almost disappointingly simple. You read it and think "well, obviously." That obviousness is the hard part. Anyone can make something complicated. Making something simple takes understanding.

So the next time you write a one-liner that makes you feel like a wizard, pause, and imagine the tired person reading it at 6 PM on a Friday before a release. Be kind to them. There's a good chance they're you.