Repository navigation
chore: gate wordy comments in production Go code - #686
Merged
Merged
Conversation
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 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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds
TestCommentsStayTersetointernal/rigor, so./dev/checkfails on a wordy comment in production Go code, and states the rule in the Comments bullet ofAGENTS.md. Test files, generated files and testdata are not checked.Why
Comments here are the
go docreference. 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,seamlessand 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>ininternal/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 aquietlycomment 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/httpsits at a similar ratio.