Skip to content
Esc

noctcore-code-quality/no-historical-comments

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.

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.

Incorrect · 2 reports
// We used to read process.env directly here.
// Before the fix this collapsed to {}.
Correct
// Caps concurrent connections to avoid pool exhaustion.
  • 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 longer describing runtime state (// Once closed, the socket is no longer writable.).
  • historical as a domain word (// Historical exchange rates are cached for a day.).

If you deliberately keep inline change-history in comments.