noctcore-code-quality/no-historical-comments
noctcore-code-quality/no-historical-comments
- Package
- code-quality v1.0.0
- Preset
- recommended
- Severity
- error
- Autofix
- No
- Suggestions
- No
- Options
- None
- Type info
- Not needed
Comments describe the current invariant, not what the code used to do.
A comment that frames code against its past — “before the fix”, “we used to”, “no longer” — rots the moment the code changes again, and it forces the reader to reconstruct a history they don’t need. The history belongs in the commit message or PR description, where it is durable and out of the way. This is also a common tell that a comment was generated to narrate a change rather than to explain the code.
What it flags
Section titled “What it flags”Line and block comments matching narrow past-framing phrases:
before/after the fix, before/after the refactor, we/this used to, used to be, we no longer,
no longer needed/used/required/necessary/supported/relevant/applies/happens/works,
kept for backwards/legacy/compat, was/were a bug/footgun, and historically.
// We used to read process.env directly here.// Before the fix this collapsed to {}.// Caps concurrent connections to avoid pool exhaustion.What it does not flag
Section titled “What it does not flag”- JSDoc
/** … */blocks, even when they mention past behaviour. - Comments that describe what the code does now (
// The pool size caps concurrent DB connections.). - Code and string literals: only comments are read.
no longerdescribing runtime state (// Once closed, the socket is no longer writable.).historicalas a domain word (// Historical exchange rates are cached for a day.).
When not to use it
Section titled “When not to use it”If you deliberately keep inline change-history in comments.