Coding Standards¶
Status: 🟢 Active | Owner: Engineering Enablement | Last Reviewed: 2025-Q4
Introduction¶
Coding standards exist to make the organisation's codebases feel as though they were written by a single disciplined team, not a collection of individuals each applying their own preferences. This consistency reduces the cognitive overhead of reading unfamiliar code, makes code review more efficient, and lowers the barrier to onboarding engineers into new codebases.
Every standard in this section is enforced automatically in CI. A failed format check, a SonarQube quality gate failure, or a linting error blocks a PR from merging. The goal is that correctness and consistency are enforced by tooling, not by individual reviewer diligence.
Separation of Concerns in Standards Enforcement¶
| Concern | Owner | How Enforced |
|---|---|---|
| Formatting (whitespace, line length, brace style) | Formatter (Black, Prettier, gofmt, google-java-format) | Pre-commit hook + CI format check |
| Linting (code quality, potential bugs) | Linter (Ruff, ESLint, golangci-lint, Checkstyle) | CI lint step (blocking) |
| Complexity and duplication | SonarQube quality gate | PR gate (blocking) |
| Security anti-patterns | SAST (Semgrep, SpotBugs, Bandit) | CI security step (blocking on Critical/High) |
| Style guide compliance | Code review | PR approval requirement |
| Comment and doc quality | Human reviewer | PR review checklist |
Formatters have authority over formatting. Linters have authority over code quality. Humans have authority over design and intent. These are complementary, not competing.
What You Will Find Here¶
| Page | Intent |
|---|---|
| Language-Specific Style Guides | Authoritative style guides, formatters, and linters for each language |
| Naming Conventions | Naming rules by language for classes, methods, variables, constants, APIs |
| Code Readability & Maintainability | Function size, guard clauses, complexity limits, error handling, the rule of three |
| Comment & Documentation Standards | When to comment, doc comment formats by language, TODO/FIXME policy |
| Linting & Static Analysis | Required linters by language, CI enforcement, SonarQube integration |
Key Standards at a Glance¶
| Standard | Rule |
|---|---|
| Formatting | Automated formatter output is authoritative; never fight the formatter |
| Cyclomatic complexity | Maximum 10 per function (SonarQube gate) |
| Function length | ≤30 lines target; >80 lines blocks merge |
| Linting | All linting errors block merge; warnings do not |
| TODO/FIXME | Must reference a Jira ticket; bare TODOs fail CI |
| Doc comments | Required on all public API surfaces |
Last reviewed: 2025-Q4 | Owner: Engineering Enablement