code-quality

Code Quality

Code quality is not aesthetics. It is one measurable thing: how fast can the next person (human or AI) change this code without breaking it? Every rule below serves that.

The hierarchy — when rules conflict, higher wins

1. Correct — handles the real input space, including the ugly parts (empty, null, duplicate, concurrent, huge, malformed).
2. Honest — the code's names, types, and structure tell the truth about what it does. No function named validate that also saves.
3. Changeable — the next likely change touches one place.
4. Consistent — matches the codebase around it. A "better" pattern that fights the codebase is worse.
5. Small/clever/fast — last, and only with evidence it matters.

Writing rules

Shape

• Functions do one thing at one level of abstraction. The test: can you name it accurately without "and"? Length is a symptom, not the rule — a 40-line straight-line function beats 5 fragmented ones you must chase.
• Depth over surface: prefer few functions with real behavior over layers of one-line delegation. Every hop a reader must follow is a cost; charge it against real value.
• Data shapes beat control flow: replacing an if/else ladder with a lookup table, an enum with exhaustive matching, or a well-typed state object usually deletes bugs. Make illegal states unrepresentable where the type system allows.

Names

• Names carry the spec: retry_delay_seconds not delay; is_eligible_for_credit not check. If a good name is impossible, the abstraction is wrong.
• Booleans read as assertions (is_, has_, can_); functions as verbs; avoid negated booleans (not_disabled) that force double negation.

Errors — where most "quality" issues actually live

• Handle or propagate, never swallow. An empty catch block is a bug with extra steps; catching broad Exception to log-and-continue hides corruption.
• Fail fast at boundaries: validate inputs where they enter (API edge, file load, config boot), then the interior trusts its inputs. Validation sprinkled everywhere means it's guaranteed nowhere.
• Error messages state what failed, with what input, and what the caller can do — written for the debugging session at 2 a.m.
• Distinguish expected failures (user error → typed error/result, clean message) from bugs (invariant broken → crash loudly). Converting bugs into handled errors hides them.