Clear is better than clever
Keep it simple, and write to the need in front of you. Build what the current goal needs, ship it good enough, and iterate. Do not add a second code path, a mode, an option or an abstraction for a need nobody has yet. Each one doubles what a reader has to hold, and the need it guessed at usually arrives in a shape nobody guessed.
Clever code scratches a real itch. It is satisfying to write and feels like proof you are good at this. It is also, almost by definition, a departure from convention, so the next person has to work out what you did and why before they can safely touch it. Good code is code someone else can maintain. That cost is not abstract: it is the bill you hand whoever works on this after you, and more and more often that is an agent reading it cold. Buzz is the evidence here: a language with close to one way to say a thing gets better agent output than the most-trained languages on earth, and explicitness is the only variable in sight.
This is not YAGNI taken whole. magus is aimed at the largest monorepos that exist (Built for the largest monorepos), and some of what that takes is engineering no sane person does for a small repository. The rule is not "never optimize". It is: clear by default, and clever only where a measurement says the clear version is too slow, with the measurement and the trade-off written beside the code.
Enforced by
- The
benchbesideanalyzer inlibs/conventionsfails an// optimization:comment, or aCacheorMemotype, in a package whose tests hold no benchmark. - The
// optimization:comment carries the measurement and the trade-off, so the clever line names its price. - Review against Capability is not a reason: a second path needs a failure it removes.
Good
Clever where it was measured, with the numbers and the cost beside it, from
cmd/magus/helpers.go:
// optimization: run the first second of every process under loadGCPercent, not only the load.
//
// measured: median wall, interleaved runs, n=60: commit-msg hook 74.1->61.6ms, tool-call hook
// 89.7->78.1ms, describe targets 240.8->233.9ms; one fewer GC each.
// trade-off: a long-lived process grows its heap 5x live for its first second.
Bad
// Load reads the config. legacy selects the old reader; lazy defers parsing until
// first use; both exist in case a future store needs them.
func Load(path string, legacy, lazy bool) (*Config, error)
Two flags for needs nobody has make four states, three of them untested. The reader pays for all four on every call site, and the store they guessed at will not look like the guess.