This item is a work in progress. It is subject to change radically at any time—up to and including being deleted entirely if I change my mind about it! Because it is a draft, it is not included in the site’s feeds; if you want to watch its progress, you will need to do that very old thing and bookmark this page and return to it over time until it is published.
Given its preliminary, work-in-progress status, I would appreciate it very much if you do not share this to social media, Hacker News, etc.—call it part of the contract for “working with the garage door open”. Thanks!
Assumed audience: Software developers of any and every skill level.
Epistemic status: There are not many things I hold about software with supreme confidence—but this is one of them.
In a recent post, I wrote:
Having only one place in the code base which must uphold a given invariant means it is far easier to test and to debug when there are failures. It means the code base does not rely on people fully internalizing the rules for each API by reading all of its comments (and those comments being correct and exhaustive!) and then being sufficiently careful everywhere they use that API. “Don’t Repeat Yourself” is most important, and most applicable, when it comes to upholding the invariants in a codebase.
This is a far more general principle than the context in which I applied it in that post, though, so here I am giving it its own home.