# Coding Standards: [project]

> The conventions reviewers enforce. Write the rule once here instead
> of a hundred times in PR comments.

| Field | Value |
|-------|-------|
| Applies to | [repo / language] |
| Owner | @name |
| Last review | YYYY-MM-DD |
| Status | Active |

## Principles

1. [e.g. Clarity beats cleverness]
2. [e.g. Match the codebase's existing style before this document]
3. [e.g. A rule that cannot be linted needs a reason in review]

## Formatting (automated)

| Rule | Tool | Config |
|------|------|--------|
| Formatting | [prettier / ruff / gofmt] | [config file] |
| Linting | [eslint / clippy] | [config file] |
| Type checking | [tsc / mypy] | strict |

Run everything: `[command]`. CI enforces it; do not rely on memory.

## Naming

| Thing | Convention | Example |
|-------|------------|---------|
| Files | kebab-case | `user-service.ts` |
| Types / classes | PascalCase | `UserService` |
| Functions | camelCase verb phrase | `fetchUser` |
| Constants | SCREAMING | `MAX_RETRIES` |

## Code structure

- Functions: [one level of abstraction / max N lines]
- Modules: [allowed dependency direction]
- Errors: [throw vs Result type; never swallow silently]
- Comments: [explain why, not what]

## Testing

- New code ships with tests; coverage floor: [N%]
- Test names describe behavior: `returns 404 when user is missing`
- Flaky tests get fixed or deleted – never muted

## Reviews

- Max PR size: [~N lines; one concern per PR]
- All checks green before requesting review
- Prefix comments: blocking vs `nit:`

## Prohibited

- [e.g. no unchecked casts / no new deps without an ADR / no stray logs]

## Exceptions

Breaking a rule is allowed when the reason is documented inline.
Silent rule-breaking is not.