Skip to content

chore: gate wordy comments in production Go code - #686

Merged
ion-alpha-dev merged 4 commits into
mainfrom
chore/comment-gate
Nov 14, 2026
Merged

ion-alpha-dev merged 4 commits into
mainfrom
chore/comment-gate

Conversation

@ion-alpha-dev

Copy link
Copy Markdown
Collaborator

What

Adds TestCommentsStayTerse to internal/rigor, so ./dev/check fails on a wordy comment in production Go code, and states the rule in the Comments bullet of AGENTS.md. Test files, generated files and testdata are not checked.

Why

Comments here are the go doc reference. Long blocks, intensifiers and accounts of how the code used to be cost every reader of that page and go stale first, and until now only a reviewer could catch them.

How to verify

Run ./dev/test ./internal/rigor/.... The rules are: a comment block over 14 lines (40 for a package comment); an em-dash, en-dash or …; a filler word (quietly, load-bearing, leverage, seamless and similar); deliberately; "this/that/which matters"; and history phrases such as "used to be", "was changed" and "we now". The patterns skip literal uses like "no longer valid", "previously stored" and "used to build".

Existing violations are listed as <file> <rule> <count> in internal/rigor/testdata/comment_baseline.txt (173 lines). The test requires each count to match exactly: a new violation fails it, and so does a count that has dropped or an entry with no violation left. A change that fixes comments must therefore lower or delete the lines it fixed, and the file can only shrink. Adding a quietly comment to any file fails the test with the file and line.

Notes for reviewers

No existing comment is rewritten here. The 14-line budget is aligned with the existing 15-line declaration-comment gate and leaves 21 over-budget blocks. A ratio of comment to code lines is not gated, since the standard library's net/http sits at a similar ratio.

Add TestCommentsStayTerse to internal/rigor. It fails on a comment block
over 14 lines (40 for a package comment), on em-dash, en-dash and
ellipsis characters, on filler words (quietly, load-bearing, leverage and
similar), on "deliberately", on "this/that matters", and on history
phrases such as "used to be" and "we now". Test files, generated files
and testdata are skipped.

Violations that predate the gate are listed by file, rule and count in
internal/rigor/testdata/comment_baseline.txt. The test requires each
count to match exactly, so a new violation fails it and so does an entry
that is stale or too high; the file can only shrink.

AGENTS.md states the rule under Comments.

Signed-off-by: Ion Alpha <contact@ionalpha.io>
@codecov

codecov Bot commented Nov 14, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

The package comment used "a diagnostic that matters", which the comment
gate rejects as filler. It now says what to do instead: write a
diagnostic that must survive a crash to stderr directly, since stray
bytes still in the guard's pipe at exit are lost.

Signed-off-by: Ion Alpha <contact@ionalpha.io>
@ion-alpha-dev
ion-alpha-dev merged commit 03792a1 into main Nov 14, 2026
34 checks passed
@ion-alpha-dev
ion-alpha-dev deleted the chore/comment-gate branch November 14, 2026 21:20
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 14, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant