Code Quality

Code Quality

Principles

Working vs Production-Ready

• Distinguish explicitly when delivering: "This works but needs X before production"
• Propose scope cuts explicitly — never implement them silently

Code Smells Checklist

Naming

• Booleans: is/has/can/should prefix
• Functions: verb prefix (get, create, handle, fetch)
• Descriptive names; avoid abbreviations unless obvious

Functions

• Single responsibility, <30 lines
• Max 3 parameters; use parameter object beyond that
• Minimize side effects
• Extract complex conditionals into named functions

Complexity

• Max 2 levels nesting; use early returns
• Replace conditional chains with lookup maps/polymorphism

Make Invalid States Unrepresentable

• Use generics / type hints to catch issues at compile-time / static analysis (Python list[str], Java List<String>, TS Array<string>)
• Use specialized types where invalid inputs are unrepresentable (pydantic BaseModel with dict[str, str] over raw str, typed keys over string constants)
• No any in TypeScript (use unknown); no force unwraps in Swift (unless provably safe)
• Use Optional / Option for null safety -- never return bare None/null when absence is possible
• Validate early at boundaries, convert to constrained types, pass constrained types downstream
• Leverage utility types: Pick, Omit, Partial, NonNullable
• Priority: compile-time > static analysis > runtime for catching errors

Anti-Patterns

Code

• Premature abstraction -- wait for 2+ concrete implementations
• God objects -- split by responsibility
• Magic values -- use named constants
• Swallowed exceptions -- handle meaningfully or propagate
• Commented-out code -- delete it, git has history

Process

• Large PRs -- keep small and focused
• Skipping tests -- costs more later
• Vague commits -- use fix: prevent null pointer in user lookup
• TODOs without context -- include why, when, ticket: // TODO(#123): handle rate limiting

Style Defaults

Naming conventions: JS/TS/Swift = camelCase, Python/Rust/Go = snake_case, Types = PascalCase, Constants = SCREAMING_SNAKE_CASE

Style Guides by Language

See each language skill for detailed naming and practice rules.

Import order (separated by blank lines): 1. Standard library, 2. Third-party, 3. Local modules

Lint Priority Triage

Safe auto-fixes: prettier --write ., eslint --fix . Manual fixes needed: type annotations, logic errors, missing error handling, accessibility

Refactoring Decision Framework

• Early returns over nested conditionals
• Parameter objects when >3 params
• Lookup maps over conditional chains
• Extract function when a block needs a comment to explain intent
• Typed errors over generic catch-all

// Early return pattern — flatten nested conditionals
function processOrder(order: Order): Result {
  if (!order.items.length) return Result.empty();
  if (!order.payment)      return Result.error('No payment');
  if (order.total <= 0)    return Result.error('Invalid total');

  return Result.ok(checkout(order));
}

Performance (Profile First)

React/Next.js: React.memo, useMemo, code splitting, virtual scrolling Database: Index frequently queried fields, batch queries (N+1), pagination API: SWR/React Query caching, debounce/throttle, parallel requests Bundle: Tree-shake, dynamic imports, route-level code splitting

Dead Code Removal

• Unused imports, unreachable code, unused variables
• Run tsc --noEmit and check lint warnings

Measurement Tools

Converted and distributed by TomeVault — claim your Tome and manage your conversions.