The Author You Are Writing For
When you write code, you are not just solving a problem for the machine. You are communicating with every developer who will touch that codebase in the future — including yourself, six months from now, with no memory of why you made the choices you did.
Long-lived software is not magic. It is the accumulation of hundreds of small decisions that prioritise clarity over cleverness, explicitness over brevity, and communication over performance (in the 95% of cases where performance does not actually matter).
Name Things for the Reader
The single highest-leverage improvement in most codebases is better names. Variables, functions, and modules that accurately describe what they do and why they exist are worth more than any amount of documentation.
There are only two hard things in computer science: cache invalidation and naming things. — Phil Karlton
Bad names force readers to hold more context in their head. Good names let them trust the name and move on.
Keep Functions Small and Honest
A function that does exactly one thing is easy to test, easy to name, and easy to replace. A function that does three things — even if they are related — is a future bug waiting to be found.
- If you cannot name a function without using "and", it probably does too much
- If a function needs a comment explaining what it does, the name is wrong
- Side effects should be explicit, not incidental
Embrace Boring Consistency
Consistency is underrated as a virtue in codebases. A team that uses the same patterns, conventions, and structures everywhere produces code that is far easier to navigate than a codebase where every developer expressed their individuality.
Linters, formatters, and architecture decision records (ADRs) are the tools of consistency. Use them aggressively.
Delete Code Ruthlessly
Dead code is not neutral. It misleads readers, increases cognitive load, and occasionally gets resurrected with bugs intact. If code is not used, delete it. Version control exists precisely so you can recover it if you were wrong.