Trim the library's comments to contracts and invariants - #53
Merged
Conversation
Comments only; no code line changes, checked by printing each file
with comments stripped and diffing against HEAD. 1263 comment lines
become 1019 across the ten library files.
The rule: an exported doc comment states the contract, not the
mechanism. An unexported comment keeps the invariant, or the reason for
a non-obvious choice. Gone are history ("used to", "the first version"),
second phrasings of one point, consequences the reader can derive,
benchmark figures, and arguments CLAUDE.md and DESIGN.md already make at
length. Every "guarded by", lock-order and "called with X held"
statement stays, and so does every reason that guards a regression:
the finished-node rule, the wait-for index's superset argument, the
warm path's ready condition, the Dekker pair, register's init-before-
queue order, the retire and release rule.
Co-Authored-By: Claude Fable 5.1 <[email protected]>
Comments only, checked as before. 1261 comment lines become 944 across eighteen test files. The five regression files carried one identical ten-line explanation of the provenance tags; it now lives once in fixtures_test.go, with every commit hash, and each file's header is its subject line. Every oracle (C1 to C11), invariant (I1 to I8) and model rule (M1 to M6) keeps its statement and the reason its exemption is safe; every test keeps its provenance tag and the sentence naming the rule it pins. Gone is the narration of how each check came to exist. Co-Authored-By: Claude Fable 5.1 <[email protected]>
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 join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Comments only, no code change: each file was printed with its comments stripped and diffed against
main, and every file matches. Library files go from 1263 comment lines to 1019, test files from 1261 to 944.The rule applied: an exported doc comment states the contract, not the mechanism; an unexported comment keeps only the invariant or the reason for a non-obvious choice. Cut: history ("used to", "the first version"), second phrasings, derivable consequences, benchmark figures, and arguments CLAUDE.md and DESIGN.md already make. Kept: every lock and ordering statement, and every reason that guards a regression.
In the tests, every oracle (C1 to C11), invariant (I1 to I8) and model rule (M1 to M6) keeps its statement and the reason its exemption is safe, and every test keeps its provenance tag and the sentence naming the rule it pins. The five regression files shared one identical ten-line explanation of the tags; it now lives once in fixtures_test.go, with every commit hash.
The package doc in di.go keeps every section and example. No CHANGELOG entry, since behaviour is unchanged.
🤖 Generated with Claude Code