Style Guides

Style guides

A style guide exists to end arguments, not to start them. Most guides fail the same way: they list opinions no tool checks, so compliance depends on whoever reviews the pull request that day, and the debates the guide was meant to settle come back one comment thread at a time.

Method

1. Write only rules a machine can enforce. Before adding a rule, name the tool and config that will check it: a .prettierrc line, an ESLint rule id, a ruff code. A rule no linter can flag is a preference, and preferences belong in mentoring, not in a document people are told to obey.
2. Adopt a standard instead of inventing one. Reach for Black, gofmt, Prettier, or ruff format and take their defaults whole. The point of a formatter is that no one owns the decision: tabs versus spaces stops being your opinion and becomes the tool's output. Bikeshedding dies when there is nothing left to paint.
3. Decide once and record why. For each genuine choice (naming, error wrapping, import order), write one line of rationale next to the rule. When someone reopens it in six months, the answer is a link, not a re-argument.
4. Enforce in CI and pre-commit, not in review. Run the formatter and linter as a pre-commit hook and as a required CI check that blocks merge. Humans review logic; machines review style. A reviewer typing "nit: spacing" is a broken pipeline, not a diligent colleague.
5. Format the whole repo in one commit, then bisect around it. Land the initial reformat as a single isolated commit and add its hash to .git-blame-ignore-revs so it never pollutes git blame. Mixing a reformat into feature commits buries every real change.
6. Allow exceptions, but make them cost a line. Permit inline overrides (// eslint-disable-next-line, # noqa) only with a trailing reason, and grep for them in review. An exceptions log kept this way shows which rules fight reality and should be loosened.
7. Change the guide by pull request. The guide is code: edits go through review, land with the enforcing config in the same commit, and take effect for everyone at once. A rule that changes by hallway consensus binds no one.

Checks

• Pick a random rule: can you point at the exact tool and config that enforces it? If not, delete it or automate it.
• Does a fresh clone pass style checks with one command, no manual steps?
• When someone questions a rule, is the answer a recorded rationale, not a fresh debate?

Boundaries

This covers style: formatting, naming, and mechanical consistency. It does not settle architecture or API shape, which need human judgment and design review. Where a language has a dominant community standard, adopt it over anything bespoke; consistency with the wider ecosystem outranks local taste.