In praise of legible systems

There’s a kind of engineering that photographs well in a demo and collapses under maintenance. It’s clever — a dense knot of abstractions that impresses in review and terrifies the person who inherits it six months later.

I’ve come to value the opposite: legibility. A legible system is one a competent newcomer can understand in an afternoon, change without fear, and explain to someone else by the end of the week.

Legibility is a feature

We treat performance and reliability as features worth investing in. Legibility deserves the same status. A system nobody understands is a system nobody can safely change — which means it slowly ossifies until it’s replaced at great expense.

Cleverness is a loan against your future understanding. Legibility pays it forward.

How to get there

• Prefer boring, obvious solutions until the problem genuinely demands more.
• Name things for what they do, not how they’re built.
• Write the paragraph of prose that explains why, and keep it next to the code.

None of this is glamorous. That’s rather the point.