Skip to content
Documentation

Code Comments and Commit Messages

FieldValue
TypeSkill Resource
Source~/.copilot/skills/technical-writing/references/code-comments.md
DescriptionNot specified

Source Content

Code Comments and Commit Messages

Anything written for people routes through this skill — including the writing that lives inside code. This surface has its own rules, and one big exemption: no two-person stories and no persona casting in code. Comments and commits are read mid-task by someone debugging; narrative here is noise.

Comments explain WHY, never restate WHAT

The code already says what it does. A comment earns its line by carrying what the code cannot say: the constraint, the tradeoff, the bug it works around, the reason the obvious approach was rejected.

// BAD: restates the code
// increment the retry counter
retries++


// GOOD: carries the why
// The upstream API returns 429 with no Retry-After header,
// so we back off exponentially instead of honoring a hint.
retries++

A comment that restates the code is a smell — delete it, or treat it as a signal that the code needs a better name. If a block needs a long comment to be followable, extract it into a well-named function and let the name do the explaining.

Commented-out code is deleted

Git remembers. A commented-out block is a question every future reader must stop and answer (“is this load-bearing?”) — delete it and let history hold it.

Doc comments for public APIs

Every exported/public symbol gets a doc comment in the house convention:

  • TypeScript — TSDoc/JSDoc: /** ... */ with @param, @returns, @throws where they add information the signature doesn’t. The first sentence is a summary; tools surface it alone.
  • Go — Go doc conventions: the comment starts with the symbol’s name (“ParseConfig reads…”), full sentences, no decoration. godoc renders it as-is.

Doc comments describe behavior and contract — inputs, outputs, errors, invariants — not implementation. Implementation notes go in regular comments next to the code they explain.

TODOs carry a name and context

Format: TODO(name): context — who owns it and enough context to act without archaeology.

// TODO(dana): remove after the v3 auth migration lands (ticket AUTH-412)

No orphan TODOs: a bare // TODO: fix this has no owner, no trigger, and no exit — it will outlive the code around it. If it matters, file it; if it doesn’t, delete it.

Commit messages

  • Subject: imperative mood, ≤ 72 characters — “add retry backoff to fetcher”, not “added” or “adds”.
  • Body: explains why, not what — the diff already shows what. Name the problem, the constraint, and any rejected alternative worth recording.
  • One logical change per commit; the subject should be honest without an “and”.

PR descriptions are a different surface with their own owner — the pr-review-checklist skill. Write commits here; write the PR story there.