Skip to content

Coding Standards

Mandatory standards

  • Write code that is readable before it is clever
  • Use clear naming for modules, classes, functions, variables, and files
  • Keep functions and components focused on one responsibility where practical
  • Prefer explicit over implicit behavior when the tradeoff is reasonable
  • Avoid copy-pasted logic when a shared abstraction would stay simple
  • Match the existing style and conventions of the repository unless a documented standard says otherwise
  • Keep public APIs small and stable
  • Prefer deterministic behavior in code paths that affect builds, tests, and operations
  • Add comments for intent, not for obvious syntax
  • Use structured logging when the stack supports it
  • Handle errors at the appropriate boundary instead of suppressing them

Logging and observability

Engineering code should emit logs and operational signals that help answer:

  • What happened
  • Where it happened
  • What context matters
  • Whether the action succeeded or failed

Error handling

  • Fail fast on invalid assumptions
  • Return useful errors to callers
  • Preserve the original failure context when rethrowing or wrapping errors
  • Avoid swallowing exceptions unless the code is deliberately handling and recovering from them

Documentation expectations

When code is not self-explanatory, the reason for the approach should be documented near the code or in the relevant engineering or architecture page.