songjiun10-collab/hncs/simplicity-budget

Complexity budget

Treat complexity like a budget. Every bit you spend now, you pay back with interest later.

YAGNI — don't build what isn't needed now

Abstractions, config options, extension points added "in case it's needed later" mostly go unused — and in the meantime make the code harder to read today.

• Is this feature, parameter, or layer needed now?
• Are you designing on top of a guess like "we might swap the DB someday"?
• Cut anything unrequested: abstractions built for a single call site, error handling for cases that can't happen
• Extensibility isn't something you build in now — it's a structure that stays easy to extend later
• Example from this codebase: Hncs's per-brand calibration scripts deliberately copy their data loader instead of sharing it — the simple choice here is duplication, because these scripts are meant to diverge experiment by experiment and a shared abstraction would be solving a problem ("what if loaders need to differ") that doesn't exist yet. But brand-agnostic orchestration code (summarize(), _paired_cv_losses()) is shared, not copied, because it's meant to stay identical everywhere — sharing is the simple choice there. Same codebase, opposite answer, because the actual variable is "does this need to diverge," not "is DRY always better."
• Principal angle: an abstraction or config knob added here becomes the template other teams copy once it ships — a speculative extension point left in shared/library code costs more than the same thing in a leaf module, because someone else will build on the wrong joint
• Distinguished/Fellow angle: an abstraction placed in a company-wide foundation risks becoming the thing that shows up in a conference talk or gets open-sourced — budget its complexity against years and every team in the org, not one quarter's roadmap
• Executive angle (CTO/VP-Eng): weigh the complexity against total cost of ownership — the infra spend, licensing, and specialized headcount it takes to run and hire for — not just the engineering hours to build it

Complexity check

• Is there a way to solve this with half the code? If 200 lines can become 50, rewrite it
• "Would a senior engineer call this overcomplicated?" — if yes, simplify
• Does each new dependency, concept, or layer actually earn its cost?
• If conditional branches keep multiplying, can the case be made not happen in the first place instead of handling it?
• A file that keeps growing isn't a neutral fact, it's a signal. Split it by responsibility.

Simple ≠ disposable

Even a one-off analysis or script, if it produced a real result, gets saved as a file. Simple and unabstracted is fine — living only in shell history or /tmp means the next person has to rebuild it from scratch.