Code Comments

PTE code comments

The bar

A comment is a failure of every better channel. Before writing one, check where the information actually belongs:

1. The code. A name, an extracted helper, or a stronger assertion often removes the need. If the mechanism can be named, name it.
2. The test. Structure that an assertion defends needs no prose: deleting the "mysterious" line makes the pinned expectation fail, and the failure explains the line better than a comment would.
3. The commit body. Diagnosis, justification, comparison with what the code used to do: all diff-relative narrative lives there.
4. Docs/skills. A house pattern gets documented once, where it is defined, never re-explained at every use site. The same comment appearing N times is a pattern that wants a name, not N comments.

What remains after those four channels is the legitimate comment: the fact a competent reader cannot recover from the code and would act wrongly without: a browser quirk, a spec constraint, a deliberate-looking-accidental choice, an invariant the code relies on but does not check. "Explains why" is necessary but not sufficient; comprehension speed alone does not earn one. The test is concrete: what wrong action does this comment prevent? No answer, no comment.

The rules

• Delete comments that restate the code. // increment the counter above counter++ is noise. So is any comment a rename would make redundant.
• Never reference ticket IDs (Linear, Jira, anything) in code comments. The codebase stands on its own; a ticket system is invisible to external contributors, dies on migrations, and the commit that introduced the line already links the context. Name the CONDITION instead of the ticket: "once merge is a first-class operation, this becomes a correction", not "TICKET-123 promotes merge...". Same rule as commits, branches, and PRs.
• Comments describe the present, never the diff. A comment that argues for the new code against code that is no longer there ("Deterministic negative assert: ...", deterministic relative to a deleted sleep) is commit-body material wearing a comment's clothes. The tell: a label or contrast that only means something to someone who saw the old version.
• Comments for an if statement go inside the if statement, not above it.
• Use backticks around code identifiers: `markDefs`, not markDefs.
• Rewrites are dense one-liners where possible: present tense, mechanism not narrative, no "we need to" preamble. "Chrome collapses the selection on blur; restore it before applying" beats three sentences of story.
• A comment that mixes a real why with restated what gets rewritten down to the why, then re-tested against the bar: the residue must still prevent a wrong action, or it goes too.