code-comments

Code comments

The default: write no comment

Code plus good naming is the primary form of explanation. A comment is an exception that must earn its place by carrying information a competent reader cannot recover from the code itself.

If you are about to write a comment, the burden is on the comment. Do not write one unless it falls under Warranted below.

Match the surrounding file first

Local convention beats this skill's defaults, always. If the file — or its neighbours — documents every public method, keep documenting them in the same shape. This skill is never a reason to strip comments from a heavily-documented codebase, nor to introduce a documentation style the repo does not use.

Scope

This governs the comments you write. It is not a mandate to delete existing comments in files you happen to touch, and it is not a docs-generation skill. The one exception: if you change code such that an adjacent comment becomes wrong, update or delete that comment — a false comment is worse than none.

Warranted

Write a comment only when it is one of these:

• Why, not what. A non-obvious decision, tradeoff, or constraint.

  // Cast: the upstream API returns numeric strings for these fields.
  $total = (int) $payload['total'];
  

• A workaround and its cause, ideally with a link — an upstream bug, a vendor quirk, a spec deviation.

  // Safari fires resize before layout settles; see https://bugs.webkit.org/show_bug.cgi?id=170595
  requestAnimationFrame(measure);
  

• Non-obvious consequences. Ordering that matters, a lock that must be held, a side effect a caller would not expect.

  // Must run before Close(): the flush path reads the connection.
  w.Flush()
  

• Genuinely subtle algorithms or math, or a regex that is not self-evident.

• Public API contracts, where the language's ecosystem expects them and the file already has them.

• TODO/FIXME only when the user asked for it or agreed to defer the work. Never a self-issued note about something you skipped — either do it or tell the user in your response.