The real test of a system is not whether it works on launch day. It is whether a developer who has never seen it can change it safely two years later.
Most software is written under conditions that will not persist. The people who built it hold context that is not written down; the deadline that shaped it is forgotten; the assumptions that made a shortcut reasonable stop being true. What remains is the code, and whether it can still be changed.
Legibility beats cleverness
A clever abstraction saves its author time once and costs every subsequent reader time repeatedly. The economics only favour cleverness when the code is never read again, which is not the case for any system worth maintaining. Explicit and slightly repetitive usually ages better than compact and indirect.
Encode decisions, not just behaviour
Code records what the system does. It rarely records why. The comment worth writing is not the one restating the line beneath it. It is the one explaining why an obvious approach was rejected. Without it, the next developer will try the obvious approach, discover the reason the hard way, and revert.
Make the safe path the easy path
- Types that make invalid states unrepresentable rather than merely discouraged
- Migrations that are reversible and tested, not written once against production
- Tests that assert business rules, so violating one fails loudly and specifically
- Environments that match, so 'works locally' carries information
- Deploys that are routine and reversible, so shipping is not an event
Every item on that list is a way of moving knowledge out of people's heads and into the system. That is the whole discipline: a codebase that a competent stranger can change confidently is worth substantially more than one that only its authors can touch, regardless of how well either performs today.
Design for the developer who inherits this, not for the one who wrote it.