code-quality

Code Quality Principles

Universal quality checklist for code reviews and implementation. Framework-agnostic.

Core Principles

DRY — Don't Repeat Yourself

• 3+ occurrences of the same pattern → extract into a reusable unit (function, module, type)
• Single source of truth — constants, types, schemas live in one place
• Shared logic belongs in a dedicated module, not copy-pasted across features
• Exception: 2 similar lines are fine. Don't extract for 2 occurrences — wait for the third.

KISS — Keep It Simple

• Simplest solution that works. No cleverness.
• If a junior dev can't understand it in 30 seconds, simplify
• Prefer boring, obvious code over elegant abstractions
• One clear way > multiple "flexible" ways
• Direct implementation > abstraction layer > framework

YAGNI — You Aren't Gonna Need It

• Don't build features before they're needed
• Don't add configurability "just in case"
• Don't create helpers for one-time operations
• Start simple, refactor when the third use case appears

SRP — Single Responsibility

• Each function does ONE thing
• Each class/module owns ONE domain
• If you need "and" to describe what it does, split it

Less Code, Same Logic

• Remove dead code completely — no commented-out code, no _unused vars
• Simplify conditionals — early returns over nested if/else
• Consolidate related variables — one object or struct over 5+ separate declarations
• Inline trivial one-liners — don't create a function for x > 0

Reusability Checklist

Extract into a reusable unit when ALL of these are true:

1. 3+ occurrences — the pattern appears in 3 or more places
2. Shared contract — the signature/API is the same across usages
3. Stable abstraction — unlikely to diverge between use cases
4. Testable — the extracted unit can be tested independently

If any condition is false, keep the code inline.

Anti-Patterns

Don't	Do
Create a helper for a one-liner	Inline it
Add a config option for a hardcoded value	Just hardcode it
Build a factory for 2 objects	Direct instantiation
Create utils.ts with 1 function	Put it where it's used
Add "flexibility" before the third use case	Wait for the pattern to emerge
Over-abstract to "prepare for the future"	Solve today's problem

Code Review Questions

Before approving code, ask:

1. Is there duplicated logic that should be extracted?
2. Could this be simpler without losing functionality?
3. Is anything here built "just in case"?
4. Does each function/component do exactly one thing?
5. Is there dead code that should be removed?