docs: tighten code comments and drop them from tests #17
No reviewers
Labels
No labels
code-review
No milestone
No project
No assignees
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
norobo/webstream!17
Loading…
Reference in a new issue
No description provided.
Delete branch "refactor/trim-code-comments"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
What
Comment-only change across 44 of the 48
*.gofiles in this repository, plus onesmall test-code change made because a comment was carrying meaning the code did
not. No production logic changed.
The branch has three commits:
8b96dd3docs: tighten code comments across the package— every productionfile, plus the larger test files.
1b57151test: drop comments from tests— every remaining test file.f6f9567fix: drop a duplicated statement in journal.loadLog— reviewfollow-up; see Review findings below.
Why
The comments had grown into design essays. On
mainthere are 172 comment blocksof six lines or more, some of them retelling the function body they sit above, and
the 32
*_test.gofiles carry 2016 comment lines — a doc comment above almostevery
func TestXxxrestating the function name, plus step-by-step narrationinside the bodies.
Rules applied
what
revive'sexportedrule in.golangci.ymlrequires, andgolangci-lint runreports 0 issues on this branch.ordering constraint, a failure mode, an on-disk or wire-format invariant, or why
an alternative was rejected. Example kept: in
store.go,journal.trimToexplains that a sealed segment's header count is an unsynced advisory rewrite
that can be understated after a crash, so a segment's end is taken from the next
segment's filename instead.
// The first loop leases the consumer and pulls the record.t.Runsubtest namesand its body are the description. Two comments remain in
*_test.goand neitheris documentation:
//go:noinlineinbench_test.go(keepsconsumeBytenon-inlinable, or the retention benchmark measures nothing) and
//go:build rapidin
journal_property_test.go(build tag).doc.go, the package documentation, keeps the architecture it is the onlyhome for (mesh routing and the leader hash, the command log, quorum acks,
retention, deduplication, consume leases, on-disk durability, security) in 121
lines instead of 189. References to internal planning-phase numbers, which a
reader of the code cannot act on, were dropped.
Code changes
Two, both accounted for:
memlog_property_test.godrewrapid.IntRange(0, 2)and labelled the casescase 0: // success,case 1: // repeat,case 2: // gap. It now drawsrapid.SampledFrom([]string{"success", "repeat", "gap"}), so the case is namedin the code and
pgregory.net/rapidreports which one failed.store.goloses a statement that commit8b96dd3had accidentallyduplicated:
j.open = j.segs[len(j.segs)-1]appeared twice injournal.loadLog. Idempotent, so no behavioural change, but it made the branchdiffer from
mainin production code. Removed inf6f9567.Every other removed comment was decoration.
Two comments were stale and were rewritten rather than left in place:
store.go, the doc comment abovefunc (seg *segment) writeRecordnamed afunction,
writeRecordLocked, that no longer exists.replicate.go,appendCommandcarried two overlapping doc paragraphs, thefirst describing behaviour the function no longer had.
Review findings
Review of
1b57151(inline comment 1206 onstore.go) found that the duplicatedline above made the branch change production code, and that the verification
below had not caught it. Both are addressed:
f6f9567.described in the first version of this description ran over
*_test.gofilesonly, because that is where the mechanical pass had caused visible damage. It
never looked at the 12 changed production files. The check now covers all 44
changed files, and this description says so.
Numbers
main(1cf83cc)*.go*_test.goDiff against
main: 44 files, +1807 / −4505.Verification
go/scannertoken-stream comparison, comments excluded,of all 44 files this branch modifies against
1cf83cc: the only differenceanywhere is the
rapid.SampledFromchange inmemlog_property_test.go. Run asgit show 1cf83cc:<file>vs the working tree, each side tokenized and compared.gofmt -l .— clean.go vet ./...— clean.go vet -tags rapid ./...— clean.golangci-lint run— 0 issues.golangci-lint run --build-tags rapid— 0 issues.go test -race ./...— ok (26s).coverage.logandbench.logare untouched: comments move neither number.Reading this diff
It is large in lines and empty in logic, so it reads best per file rather than as
one patch.
server.go,store.go,replicate.goandstream_state.gohold mostof the rewritten prose; the other production files are a handful of one-line doc
comments each; every
*_test.goexceptmemlog_property_test.gois deletionsonly.
A test's name, its subtest names and its body say what it does and what it is for: a doc comment above the function restated the name, and the comments inside it narrated the steps the following lines already perform. Both are gone. Only two comments remain in the *_test.go files, and neither is documentation: bench_test.go //go:noinline (keeps consumeByte non-inlinable) journal_property_test.go //go:build rapid (build tag) Two places needed a code change rather than a deletion, because a comment was carrying meaning the code did not: - memlog_property_test.go drew an int 0..2 and labelled the cases with "// success", "// repeat" and "// gap". It now draws rapid.SampledFrom([]string{"success", "repeat", "gap"}), so the case is named in the code and rapid reports which one failed. - nothing else: every other removed comment was decoration. Verified that no code changed: for each modified test file, the go/scanner token stream of the working tree equals the token stream of the same file at HEAD (comments excluded). The only token difference is the SampledFrom change above. go vet (also with -tags rapid), golangci-lint (also with --build-tags rapid), gofmt and go test -race are all clean.Comment-only PR, reviewed as
pi-revieweragainst the head1b57151with a local worktree and the repo's own toolchain (go1.27.1).Verified true (each claim reproduced in-session):
gofmt -l .clean;go vet ./...andgo vet -tags rapid ./...clean;golangci-lint run0 issues (plain and--build-tags rapid);go test -race ./...ok (23.8s); rapid property tests (TestMemlogProperties,TestJournalMemlogParity) pass..gofiles touched (go.mod/go.sum/coverage.log/bench.log unchanged); only the two non-doc comments remain in*_test.go(//go:noinline,//go:build rapid).memlog_property_test.go:rapid.IntRange(0,2)->rapid.SampledFrom([]string{...})is behavior- and distribution-preserving (uniform 3-way;SampledFromexists in pinned rapid v1.3.0 pergo doc pgregory.net/rapid.SampledFrom) and genuinely improves failure output. Good change.doc.goand the rewritten production comments were cross-checked against the code: leader hash (hashLeader/leaderHash, server.go:856/873), quorum formula (replicaQuorum = len(set)/2+ own copy, replicate.go:326), relay set (server.go:929frameStreamName), lease semantics (consumerLeaseTimeout, zero-lease opt-out, consumer_state.go:52), durability layout (stream.meta/consumers.meta/cursors.meta, store.go:26-29), base/next derivation, budget default (defaultStorageBytes, server.go:575), limits (maxStreamsPerServer/maxConsumersPerStream/maxStreamsPerPeer), and every referenced exported symbol exists. Spot-checked rewrites (journal.trimTo,appendCommand,relayedStreamName,codeNoQuorum) are accurate.One issue - REQUEST_CHANGES: the PR's central claim is false. A go/scanner token-stream comparison (comments excluded) of all 44 files between base
1cf83ccand head1b57151finds TWO code differences: the intendedSampledFromchange and a duplicated statement instore.gointroduced by commit8b96dd3. The duplicate is idempotent (no runtime behavior change), but it is a production code change in a comment-only PR, and the described verification gate ('the only token difference in the whole branch is the SampledFrom change') did not catch it - see the inline comment.@ -748,2 +723,2 @@// is both the append position and — since the bytes before it were read back — the durable end a// failed batch rolls back to.// The newest segment is the open one, retained for appends.j.open = j.segs[len(j.segs)-1]🟠 IMPORTANT — duplicated production statement, and the PR's 'no code changed' claim is false.
loadLognow containsj.open = j.segs[len(j.segs)-1](with its comment) twice — head store.go lines 721 and 724 — while main has it once. Reproduced with:git show 1b57151:store.go | grep -n 'j.open = j.segs'→ lines 721, 724;git show 1cf83cc:store.go | grep -c 'j.open = j.segs\[len(j.segs)-1\]'→ 1; and a go/scanner token comparison (comments excluded) across all 44 changed files: onlymemlog_property_test.go(intended) andstore.go(unintended) differ.Condition under which it matters: none at runtime — the second assignment is idempotent and
loadLogis not hot, so there is no behavioral change. What does break is the PR's stated verification: the token-equality gate described in the description ('the only token difference in the whole branch is the SampledFrom change') demonstrably missed this, and the same mechanical pass the description admits swallowed code lines in four test files also edited a production file without notice.Fix: delete the duplicated comment + statement (head lines 722-724), then re-run the token comparison — it should then report only the SampledFrom change. Consider adding the token-equality check as a CI gate so 'comment-only' PRs cannot silently ship code changes.
Resolving the finding in review 66 (inline comment 1206): the duplicated statement in
store.gointroduced by8b96dd3.Fixed in
f6f9567—journal.loadLoghadThe second pair is deleted; one assignment with one comment remains, as on
main.git show f6f9567:store.go | grep -c 'j.open = j.segs\[len(j.segs)-1\]'→1.Why the gate missed it, stated plainly: the token-equality check reported in the description ran as
and compared only test files, because that is where the mechanical pass had visibly swallowed code. It never looked at the changed production files, so a duplicated statement in
store.gowas invisible to it while the description claimed the check covered "every modified file". The claim was wrong when written.Re-verified over all 44 changed files (
git diff --name-only 1cf83cc..HEAD), each side tokenized withgo/scannerand compared, comments excluded:That is the intended
rapid.SampledFromchange and nothing else. The description now says the check covers all 44 files, and records what the earlier version actually did.Re-ran after the fix:
gofmt -l .clean;go vet ./...andgo vet -tags rapid ./...clean;golangci-lint runandgolangci-lint run --build-tags rapid0 issues;go test -race ./...ok (26s). Diff againstmainis now 44 files, +1807 / -4505.On the suggested CI gate: agreed it is the durable fix, and I have not added it here because this branch is meant to be comment-only and a workflow plus a checker script would be the third kind of change in it. Happy to follow up on a separate branch (
ci/comment-only-token-gate) that adds the token-equality check to.forgejo/workflows/, comparing every changed.gofile against the base commit and failing when the token stream differs. Say the word and I will open it.Please re-review at
f6f9567.