Coding Standards & Best Practices

⚠️ NON-NEGOTIABLE RULES (apply before anything else)

Rules are ordered by impact on readability, maintainability, comprehensibility, and evolvability — highest impact first.

1. NEVER mutate objects or arrays — always use spread (or immutable methods). Mutations break predictability, debugging, and React’s model; they make refactors and evolution risky.
2. NEVER use any — define precise interfaces/types. Types are the main documentation and safety net; any removes both and makes the codebase hard to understand and change.
3. NO inline types — extract types/interfaces to named declarations. Single source of truth, reuse, and self-documenting code; changes stay in one place.
4. NO deep nesting — use early returns. Flat control flow is the largest readability win; nested conditionals are hard to scan and maintain.
5. Functions under 50 lines / Files under 800 lines — split when exceeded. Small units are scannable, testable, and keep a single responsibility; large blocks are the opposite.
6. ALWAYS handle errors in async functions with try/catch — never swallow silently; add context to messages and rethrow when the caller must know. Unhandled or silent errors make behavior incomprehensible and bugs hard to fix.
7. NO magic numbers or unexplained strings — extract as named constants. Names explain intent and centralize values for safe evolution.
8. Prefer ?? over || for null/undefined — nullish coalescing only replaces null/undefined; || also replaces 0, "", and false, which often causes subtle bugs.
9. ALWAYS use arrow functions at top level — const fn = () => {}; no function keyword for module-level functions. Consistent style reduces cognitive load.
10. React: use setState updater when the next state depends on the previous — setCount((prev) => prev + 1). Using count directly can be stale and cause wrong behavior.
11. React: explicit booleans in conditionals — e.g. hasItems && <List />, not items.length && <List /> (avoids rendering 0). Conditionals must be clearly boolean.
12. React: list keys from stable id — prefer key={item.id} (or stable id); avoid key={index} unless the list is static and not reordered.
13. useEffect: always return a cleanup when you set up subscriptions, intervals, or listeners — avoids leaks and updates after unmount.