Most code is written once and read many times. The ratio is probably ten to one, maybe higher. And yet we optimize for writing speed, not reading ease.

The trap of cleverness

There is a particular kind of satisfaction in a clever solution. A one-liner that does what twenty lines would do. A recursive function so elegant it feels like mathematics. I have written both and been proud of both.

The problem is that clever code is often opaque code. Six months later, reading it cold, even its author may struggle to reconstruct the reasoning.

# Clever
result = [x for xs in nested for x in xs if x % 2 == 0]

# Clear
result = []
for group in nested:
    for value in group:
        if value % 2 == 0:
            result.append(value)

Both are correct. One requires a double-take.

Names matter more than comments

Comments explain what the code does. Good names make that explanation unnecessary.

# Bad
def proc(d, t):
    return [x for x in d if x['ts'] > t]

# Good
def filter_recent_events(events, cutoff_timestamp):
    return [e for e in events if e['timestamp'] > cutoff_timestamp]

The second version needs no comment. The function name, the parameter names, the variable name. They tell the whole story.

Small functions, clear seams

A function that fits on one screen is a function you can understand. A function that requires scrolling is a function that is doing too much.

The rule I try to follow: if I need to add a comment to explain a block of code, that block probably wants to be a function with a name.

Conclusion

Writing code that lasts is a form of consideration for future readers, yourself included. It costs a little more time now and saves a lot of time later.