Coding Standards

Coding standards are team agreements about how code should be written:

• Naming conventions (camelCase vs snake_case)
• Formatting (tabs vs spaces, brace placement)
• Code organization (file structure, module boundaries)
• Patterns (how to handle errors, how to structure tests)

Standards enable collective ownership. When code looks the same everywhere, anyone can read any code. There's no "translation" between Bob's style and Alice's style.

Standards also reduce friction in code review. Instead of debating formatting, you discuss logic and design. The bikeshedding goes away.

Without standards: Every file feels different. Moving between modules requires mental context-switching. Code review becomes style warfare.

With standards: The codebase feels unified. Reading unfamiliar code is easier. Reviews focus on what matters.

Not all conventions are equal. Distinguish between:

Semantic standards: Affect code behavior or maintainability

• Error handling patterns
• Logging conventions
• Test structure
• API design patterns

Stylistic standards: Affect appearance only

• Formatting (indentation, line length)
• Naming (camelCase vs snake_case)
• Brace placement

Semantic standards deserve discussion. How the team handles errors is a meaningful decision with real consequences.

Stylistic standards should be automated. Use Prettier, Black, gofmt—tools that format code automatically. Don't waste human time on tabs vs spaces.

The goal is to remove friction, not to achieve some platonic ideal of code style.

Modern tooling can enforce most standards automatically:

Formatters: Prettier (JavaScript), Black (Python), gofmt (Go), rustfmt (Rust)

• Run on save or as a pre-commit hook
• Eliminate formatting discussions entirely

Linters: ESLint, Pylint, Clippy, RuboCop

• Catch style violations and potential bugs
• Configurable to team preferences
• Run in CI to prevent non-compliant code from merging

Type checkers: TypeScript, mypy, Flow

• Enforce type consistency
• Catch errors before runtime

Pre-commit hooks: Husky, pre-commit

• Run checks before code is committed
• Catch issues before they enter the repository

Configure once, enforce forever. Don't rely on human discipline—automate it.

Standards can trigger strong opinions. Avoid endless debate:

Start with existing conventions. If the language or framework has standard style (Go, Rust), just use it. Don't reinvent.

Use industry defaults. Popular linter/formatter configs (Airbnb ESLint, Google style guide) are battle-tested.

Decide quickly, adjust later. Pick something reasonable. If it proves problematic, change it. Don't block progress waiting for the perfect standard.

Make it democratic but decisive. Let the team vote on contentious issues. Majority wins. The minority accepts the decision.

Remember the goal. Standards exist to reduce friction, not to express preferences. If a discussion is taking too long, any reasonable choice is fine.

Standards should be documented—but keep them living:

What to document:

• Semantic standards (how to handle errors, test patterns)
• Rationale for non-obvious choices (why we chose X over Y)
• Exceptions and when to break rules
• How to propose changes

Where to document:

• README or CONTRIBUTING file in the repo
• Wiki or team documentation space
• Comments in the linter/formatter config

Keep it current. Outdated documentation is worse than no documentation. When you change a standard, update the docs.

Make it findable. New team members should find the standards easily. Don't bury them in a wiki maze.

The best documentation is the code itself. If your standards are enforced automatically, the code demonstrates what's acceptable.