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.