CONTRIBUTING and the operating rules both say zero comments by default, only a WHY the code cannot show or a functional pragma. The rule does not bind, and the reason is that it has no checkable form: a worker can always construct a WHY for any comment, and the reviewer is then arguing taste.
Measured
Worker-authored added Go comment lines, read in file order on each PR:
So the bodies are mostly defensible. That is the point: the rule is passing every case it is applied to while the volume keeps climbing, which means it is not the thing doing the work.
The concentration is in test comments, and they share one shape - the first clause restates the test function name, then the real content follows. Example shape:
// TestFooRefusesBarWhenBazDiffers is the counter-proof the brief asks for:
// <three more lines of genuinely useful reasoning>
The first line is pure restatement. It is also the line that makes the block long enough to feel like documentation.
Ask
Two rules, both checkable without judgment:
- A comment may not open with the identifier it documents.
- A comment block may not exceed three lines.
Both are lintable. Neither requires anyone to adjudicate whether a WHY is real, which is what makes the current rule unenforceable.
Rule 2 will occasionally be wrong - a genuinely subtle invariant sometimes needs four lines. That is acceptable: a rule that is right most of the time and mechanically enforced binds harder than one that is right always and enforced never. Add an escape hatch only if a real case appears.
Done when
- both rules are enforced by the lint step rather than by a reviewer reading a diff
- the rules are stated in CONTRIBUTING in their checkable form, replacing the unfalsifiable version
CONTRIBUTING and the operating rules both say zero comments by default, only a WHY the code cannot show or a functional pragma. The rule does not bind, and the reason is that it has no checkable form: a worker can always construct a WHY for any comment, and the reviewer is then arguing taste.
Measured
Worker-authored added Go comment lines, read in file order on each PR:
So the bodies are mostly defensible. That is the point: the rule is passing every case it is applied to while the volume keeps climbing, which means it is not the thing doing the work.
The concentration is in test comments, and they share one shape - the first clause restates the test function name, then the real content follows. Example shape:
The first line is pure restatement. It is also the line that makes the block long enough to feel like documentation.
Ask
Two rules, both checkable without judgment:
Both are lintable. Neither requires anyone to adjudicate whether a WHY is real, which is what makes the current rule unenforceable.
Rule 2 will occasionally be wrong - a genuinely subtle invariant sometimes needs four lines. That is acceptable: a rule that is right most of the time and mechanically enforced binds harder than one that is right always and enforced never. Add an escape hatch only if a real case appears.
Done when