Repository navigation
docs: thin the commentary back to what the code does not say - #4
Merged
Merged
Conversation
190 comment lines go: a doc over a test that only said the test's name again, and the second and third paragraphs of a private item's doc where they argued with an alternative rather than describing the thing. What was deliberately left alone, after a first pass cut too much and was thrown away: anything naming the reference implementation, the differential suite, a rounding or endianness rule, a spec clause, or a recorded trap — and every doc under tests/, where the comment says why a case exists, which is the one thing the code beside it cannot say. Nothing public lost a line. 179 tests, fmt and clippy clean.
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.
The same pass as
xtce-gs#9: the comments had drifted from describing the code to arguingwith the alternatives, and a doc over a test whose name is already a sentence says it twice.
The rule
src/keeps its summary paragraph and loses the rest;tests/is touched — a comment there says why the case exists, which is theone thing the code beside it cannot say.
What is protected, by name: the reference implementation and the differential suite, the
no-panic gate, rounding, endianness and alignment rules, spec clauses, and recorded traps.
The first attempt at this cut roughly half again as much and was thrown away: a sample of what
it removed turned out to be the calibrator's summation order, which
io::ErrorKinds aretransient on which source, and why the generated load uses the narrowest integer that spans a
field. Those are facts, not opinions, and the protection list grew until they survived.