Comments

The best comment is the code that made it unnecessary. Every comment is a small admission that the code could not speak for itself — sometimes justified, usually not. Before you write one, try to delete the need for it: rename the variable, extract the function, name the constant. When a comment survives that test, keep it and make it excellent. When it doesn't, the code is the comment.

This file is about the comments that earn their place and the ones that rot. For the naming and extraction techniques that dissolve most comments before they're written, see meaningful-names and functions.

Comments go stale

Code is executed; comments are not. The compiler checks the code and ignores the prose, so when the spell changes and the comment doesn't, the comment quietly becomes a lie. A stale comment is worse than no comment — a missing comment sends you to read the code, but a wrong one sends you the wrong way with full confidence. Prefer code that cannot drift out of sync with itself.

// Bad — the comment says 3, the code says 5; which one is the rule?
// A wizard may hold at most 3 active spells at once.
const MAX_ACTIVE_SPELLS = 5

const canCastSpell = (wizard: Wizard): boolean => {
  return wizard.activeSpells.length < MAX_ACTIVE_SPELLS
}