| FazBrowse GitHub Viewer | Trending | | Home |
| Tools: [Download Repo ZIP] [Original HTTPS Page] |
Sorry, something went wrong.
The rule meant to prevent over-commenting lived only in individual contributors' homedir config, so it bound nobody else, and it carried no length constraint. Add a Comments section to the repo file instead. Wording is the shortest of five measured variants that passes both a must-stay-quiet fixture and a needs-orientation fixture. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
|
||
| ## Comments | ||
|
|
||
| Never narrate what the code does. Comment only a fact a reader cannot recover from the code. One line each; never a paragraph. |
There was a problem hiding this comment.
One line each; never a paragraph.
Seems drastic, since I often write paragraphs to explain why the code does something. but, seems better to include than not, to reduce the current level of over-explaining.
Sorry, something went wrong.
| Back | FazBrowse Home | New Git URL |
This PR adds a comment style block to AGENTS.md to attempt to reduce comment verbosity and density.
Before and after
Same task, same file, identical function body. Only the comment differs. The task plants one fact the code cannot show: this sort has to match the collation a Rails helper uses, or pagination between the two views disagrees.
Without it:
With it:
Two more exports from the same file, again byte-identical bodies.
Without it:
With it:
Across three attempts each, the file carried 16, 9, and 12 comment lines without the section, and 2, 2, and 2 with it.
Context cost
59 new tokens but it should be a net decrease as time & tokens spent on reducing comment verbosity go away.
Links
Testing story
I built a test harness on Opus which is instructed to spawn Sonnet subagents which reads context and writes a file. Variations of the AGENTS.md file were submitted to subagents, and a score was assigned to commenty verbosity and denisty along with a blinded judge. I inspected the results for quality, verbosity, and density.
Five wordings, three runs per module, twenty-seven simulations.
Wordings shorter than this one lost the paragraph on consentStore.ts. Wordings longer than it put a docblock on every export of sectionRoster.ts.