Document a rationale for every disabled lint rule

This is a principle

A reusable technical claim: something I would want true in any of my work.

Claim. Every lint rule you disable (or reconfigure away from its default) must carry an inline comment explaining why. No silent, unexplained suppressions.

Why. A bare "MD013": false is indistinguishable from an accident: a future maintainer can't tell whether it's a considered decision or leftover cruft, so they either cargo-cult it or remove it and reintroduce the problem it was solving. A one-line rationale converts tribal knowledge into durable, in-context documentation - read exactly where the decision lives - and makes it safe to revisit later. The same logic extends to any per-line # noqa / # type: ignore: name the reason.

Snippet.

{
  "config": {
    // MD013: Line length — disabled; prose wraps naturally, enforcing hurts readability
    "MD013": false,
    // MD046: Code block style — MkDocs admonitions look like indented code to the linter
    "MD046": false
  }
}

How enforced. Convention upheld in review: a disabled rule without a rationale is a review blocker. Kin to Guard invariants at commit-time, not review-time - here the "invariant" is that decisions stay explained.

Backlinks

The following pages link to this page:

• Principles