Coding Standards

Team conventions for naming, formatting, error handling, testing, and code-review etiquette. These standards align with widely adopted style guides (Airbnb JavaScript, Google TypeScript) and the SOLID and Clean Code principles, adapted for our stack.

Naming

• Components — PascalCase filenames and exports (UserCard.tsx).
• Utilities & hooks — camelCase (formatDate.ts, useDebounce.ts).
• Constants — SCREAMING_SNAKE_CASE (MAX_RETRY_COUNT).
• CSS variables — kebab-case (--primary-foreground).
• Prefer descriptive names over abbreviations; avoid Hungarian notation.

Formatting & Linting

Prettier is the source of truth for formatting. ESLint enforces code quality. Both run in pre-commit hooks and CI. Disabling a rule requires a comment explaining the reason and a linked issue when the suppression is temporary.

TypeScript

• strict is enabled — no any unless documented with a // FIXME(scope): comment.
• Use interface for component props and public object shapes; type for unions, intersections, and mapped types.
• Prefer readonly arrays/properties for inputs you don't mutate.
• Validate at boundaries (HTTP, queues, env) with a schema library (Zod or Valibot) — never trust untyped JSON.
• Export prop interfaces alongside their component.

SOLID at a Glance

Error Handling

• Use typed Result-like returns or domain-specific error classes — never throw plain strings.
• Catch errors at the lowest layer that can act on them. Re-throw with context where needed.
• In HTTP handlers, map domain errors to RFC 9457 problem responses; never leak stack traces to clients.
• Log errors once, at the boundary, with structured fields (requestId, userId, code).

Testing Pyramid

Git & Commits

• Conventional Commits: feat:, fix:, docs:, refactor:, test:, chore:.
• Imperative subject ≤ 72 chars; body explains why, not what.
• Trunk-based development: short-lived feature branches; rebase before merge.

Code Review Etiquette

• Keep PRs small and focused — one concern per pull request.
• Resolve all linting and type errors before requesting review.
• Use the nit / suggestion / blocking convention to signal severity. Suggest alternatives when blocking.
• Approve quickly when ready; assume good intent.