Code Is Read More Than It Is Written
This is one of the most quoted maxims in software, and one of the least internalised. If code is read 10x more than it's written, you should spend roughly 10x the energy on readability relative to cleverness. Most teams do the opposite.
I'm not talking about comments — I think over-commenting is actually a smell that the code itself is unclear. I'm talking about naming, structure, and the relentless elimination of unnecessary complexity.
The Questions I Ask Before Merging
Before I merge any non-trivial change, I ask myself:
- Would someone unfamiliar with this context understand what this code does in 30 seconds? Not how it works — what it does.
- Is every abstraction justified? An abstraction that exists for one use case is usually just obfuscation.
- Have I removed everything that doesn't need to be there? The best code is deleted code.
A Note on "Clean Code"
The "clean code" movement has done some good and some harm. The harm comes from treating its rules as absolute — functions should be tiny, comments are a failure, every duplication must be extracted.
These are heuristics, not laws. A 50-line function that reads top-to-bottom with no branching is often cleaner than four 12-line functions that call each other in non-obvious ways.
The real principle underneath "clean code" is: reduce the cognitive load on the next reader. Sometimes that means a shorter function. Sometimes it means a longer one.
What "Long Term" Actually Means
When I say "write for the long term," I mean: write for the person who will be on-call at 2am six months from now, under pressure, with no context. That person might be you.
They need to:
- Find the relevant code fast
- Understand what it's doing without reading the whole codebase
- Make a change with high confidence that they're not breaking something else
- Roll back cleanly if they are
Every architectural and naming decision you make either helps or hurts those four goals.
The Practical Upshot
None of this requires grand refactors or heroic engineering. It's a habit. It's the habit of, every time you write a line of code, asking: will this be obvious to a tired engineer at 2am?
If the answer is no, make it so.