Skip to content

Commit 1144fe8

Browse files
author
gluck
committed
skills: the code that ships carries no comments
The rule has been in force in practice and nowhere in writing, so every agent read the surrounding files, found paragraphs of justification above every function, and matched them. Name it in maintaining.md beside the loop, including the part that is easy to miss: the existing commentary is the backlog, not the house style, and a comment a change has made false gets deleted rather than edited.
1 parent 5690bd8 commit 1144fe8

1 file changed

Lines changed: 21 additions & 0 deletions

File tree

‎skills/figaro/contributing/maintaining.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -154,6 +154,27 @@ Two ways this goes wrong, both seen:
154154
Rebase it deliberately, hunk by hunk, or rewrite it. Never `git am` a stale
155155
patch and call the bug closed.
156156

157+
### No comments in the code that ships
158+
159+
Non-test Go files carry zero comments. No function header, no inline note,
160+
no line beside a constant explaining why the constant is what it is. The
161+
justification goes in the commit message and in the handoff; both are dated,
162+
attributed, and cannot rot in place the way a `//` does.
163+
164+
This tree is full of long explanatory comments from before the rule. **They
165+
are not a style to match.** A file thick with commentary is the backlog, not
166+
permission, and an agent that mirrors its surroundings is the reason the
167+
backlog grows. When a change makes a nearby comment false, delete that
168+
comment rather than updating it: a sentence nobody is maintaining is worse
169+
than silence.
170+
171+
Tests may be commented. A test is the one place where the reason for the
172+
assertion cannot be read off the code, because the failure it defends against
173+
is absent by construction.
174+
175+
If the reason truly cannot leave the file, the code is the problem. Rename,
176+
split, or narrow the types until a reader needs no narration.
177+
157178
### One worktree per independent fix
158179

159180
Two unrelated repairs in one branch cannot be reviewed, bisected or reverted

0 commit comments

Comments
 (0)