comments

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# 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](../meaningful-names/SKILL.md) and [functions](../functions/SKILL.md).

## 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.

```ts
// 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
}
```

```ts
// Good — the constant name carries the rule; nothing can drift
const MAX_ACTIVE_SPELLS_PER_WIZARD = 5

const canCastAnotherSpell = (wizard: Wizard): boolean => {
  return wizard.activeSpells.length < MAX_ACTIVE_SPELLS_PER_WIZARD
}
```

## Explain WHY, not HOW

The code already tells you *how* — that is its whole job. A comment that narrates the mechanics just duplicates the code in a second language that no compiler checks. Spend comments on the *why*: the intent, the business reason, the non-obvious constraint. Those are the things the code genuinely cannot express.

```ts
// Bad — narrates the "how" the reader can already see
// Loop over the students and add 10 points to each one's house.
students.forEach((student) => {
  awardPoints(student.house, 10)
})
```

```ts
// Good — explains the "why", which the code cannot show
// The Ministry's Decree No. 24 requires every attending student to earn
// the base participation points before the Sorting feast results are sealed.
students.forEach((student) => {
  awardPoints(student.house, PARTICIPATION_POINTS)
})
```

## Good comments protect from well-meaning mistakes

Some comments are guardrails. They exist to stop a future developer — often a competent, well-intentioned one — from "cleaning up" something that must stay exactly as it is. When correctness depends on an order, a delay, or a workaround that looks wrong, say so, or someone will helpfully break it.

```ts
// Bad — no warning; the next reader "tidies" the order and ruins the potion
const brewPolyjuice = (cauldron: Cauldron): Potion => {
  cauldron.add(LACEWING_FLIES)
  cauldron.add(LEECHES)
  cauldron.simmer(SIMMER_MINUTES)
  cauldron.add(POWDERED_BICORN_HORN)
  return cauldron.bottle()
}
```

```ts
// Good — the warning defends the invariant
const brewPolyjuice = (cauldron: Cauldron): Potion => {
  cauldron.add(LACEWING_FLIES)
  cauldron.add(LEECHES)

  // Do NOT reorder: the bicorn horn must go in only AFTER the full simmer,
  // or the potion turns to sludge (see Moste Potente Potions, p.87).
  cauldron.simmer(SIMMER_MINUTES)
  cauldron.add(POWDERED_BICORN_HORN)

  return cauldron.bottle()
}
```

## Code vs docs

Your team reads the code; the world reads the docs. That difference decides where a comment belongs. A published package surface — anything another team or the public imports — deserves real doc comments (TSDoc) that describe the contract without forcing readers into the implementation. Internals, which only your team touches, rarely do: the code is right there.

```ts
// Good — public API of a shared package; TSDoc documents the contract
/**
 * Casts a spell on a target and returns the resulting effect.
 *
 * @param spell - The incantation to cast. Must be a known, non-Unforgivable spell.
 * @param target - The wizard or creature the spell is aimed at.
 * @returns The applied {@link SpellEffect}.
 * @throws {ForbiddenSpellError} If the spell is an Unforgivable Curse.
 */
export const castSpell = (spell: Spell, target: Target): SpellEffect => {
  // ...
}
```

```ts
// Bad — TSDoc ceremony on a private helper no one imports; pure clutter
/**
 * Adds points.
 * @param house the house
 * @param points the points
 */
const addPoints = (house: House, points: number): void => {
  house.points += points
}
```

## Redundant comments are noise

If the code already says it, the comment says it twice — and now there are two things to keep in sync instead of one. Redundant comments add reading cost, add rot risk, and pay nothing back. Delete them and let the identifier do the talking.

```ts
// Bad — every line restates the obvious
class Wizard {
  // The name of the wizard

From hzblj/skills, MIT.

More from hzblj/skills