docs: tighten code comments and drop them from tests #17

Merged
sam merged 3 commits from refactor/trim-code-comments into main 2026-10-20 06:33:07 +00:00
Member

What

Comment-only change across 44 of the 48 *.go files in this repository, plus one
small test-code change made because a comment was carrying meaning the code did
not. No production logic changed.

The branch has three commits:

  1. 8b96dd3 docs: tighten code comments across the package — every production
    file, plus the larger test files.
  2. 1b57151 test: drop comments from tests — every remaining test file.
  3. f6f9567 fix: drop a duplicated statement in journal.loadLog — review
    follow-up; see Review findings below.

Why

The comments had grown into design essays. On main there are 172 comment blocks
of six lines or more, some of them retelling the function body they sit above, and
the 32 *_test.go files carry 2016 comment lines — a doc comment above almost
every func TestXxx restating the function name, plus step-by-step narration
inside the bodies.

Rules applied

  • Exported identifiers keep a godoc comment opening with their name. That is
    what revive's exported rule in .golangci.yml requires, and
    golangci-lint run reports 0 issues on this branch.
  • A comment stays only if it carries what the code cannot: a locking or
    ordering constraint, a failure mode, an on-disk or wire-format invariant, or why
    an alternative was rejected. Example kept: in store.go, journal.trimTo
    explains 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.
  • A comment that restates the next line is deleted, e.g.
    // The first loop leases the consumer and pulls the record.
  • Test comments are gone entirely. A test's name, its t.Run subtest names
    and its body are the description. Two comments remain in *_test.go and neither
    is documentation: //go:noinline in bench_test.go (keeps consumeByte
    non-inlinable, or the retention benchmark measures nothing) and //go:build rapid
    in journal_property_test.go (build tag).
  • doc.go, the package documentation, keeps the architecture it is the only
    home 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.go drew rapid.IntRange(0, 2) and labelled the cases
    case 0: // success, case 1: // repeat, case 2: // gap. It now draws
    rapid.SampledFrom([]string{"success", "repeat", "gap"}), so the case is named
    in the code and pgregory.net/rapid reports which one failed.
  • store.go loses a statement that commit 8b96dd3 had accidentally
    duplicated: j.open = j.segs[len(j.segs)-1] appeared twice in
    journal.loadLog. Idempotent, so no behavioural change, but it made the branch
    differ from main in production code. Removed in f6f9567.

Every other removed comment was decoration.

Two comments were stale and were rewritten rather than left in place:

  • In store.go, the doc comment above func (seg *segment) writeRecord named a
    function, writeRecordLocked, that no longer exists.
  • In replicate.go, appendCommand carried two overlapping doc paragraphs, the
    first describing behaviour the function no longer had.

Review findings

Review of 1b57151 (inline comment 1206 on store.go) found that the duplicated
line above made the branch change production code, and that the verification
below had not caught it. Both are addressed:

  • The duplicate is deleted in f6f9567.
  • The reason it slipped through is stated plainly: the token-equality check
    described in the first version of this description ran over *_test.go files
    only, 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) this branch
comment lines, all *.go 5203 2517
comment lines in *_test.go 2016 2
comment blocks of 6+ lines 172 60

Diff against main: 44 files, +1807 / −4505.

Verification

  • No code changed: a go/scanner token-stream comparison, comments excluded,
    of all 44 files this branch modifies against 1cf83cc: the only difference
    anywhere is the rapid.SampledFrom change in memlog_property_test.go. Run as
    git 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.log and bench.log are 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.go and stream_state.go hold most
of the rewritten prose; the other production files are a handful of one-line doc
comments each; every *_test.go except memlog_property_test.go is deletions
only.

## What Comment-only change across 44 of the 48 `*.go` files in this repository, plus one small test-code change made *because* a comment was carrying meaning the code did not. No production logic changed. The branch has three commits: 1. `8b96dd3` `docs: tighten code comments across the package` — every production file, plus the larger test files. 2. `1b57151` `test: drop comments from tests` — every remaining test file. 3. `f6f9567` `fix: drop a duplicated statement in journal.loadLog` — review follow-up; see *Review findings* below. ## Why The comments had grown into design essays. On `main` there are 172 comment blocks of six lines or more, some of them retelling the function body they sit above, and the 32 `*_test.go` files carry 2016 comment lines — a doc comment above almost every `func TestXxx` restating the function name, plus step-by-step narration inside the bodies. ## Rules applied - **Exported identifiers keep a godoc comment opening with their name.** That is what `revive`'s `exported` rule in `.golangci.yml` requires, and `golangci-lint run` reports 0 issues on this branch. - **A comment stays only if it carries what the code cannot:** a locking or ordering constraint, a failure mode, an on-disk or wire-format invariant, or why an alternative was rejected. Example kept: in `store.go`, `journal.trimTo` explains 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. - **A comment that restates the next line is deleted**, e.g. `// The first loop leases the consumer and pulls the record.` - **Test comments are gone entirely.** A test's name, its `t.Run` subtest names and its body are the description. Two comments remain in `*_test.go` and neither is documentation: `//go:noinline` in `bench_test.go` (keeps `consumeByte` non-inlinable, or the retention benchmark measures nothing) and `//go:build rapid` in `journal_property_test.go` (build tag). - **`doc.go`**, the package documentation, keeps the architecture it is the only home 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.go`** drew `rapid.IntRange(0, 2)` and labelled the cases `case 0: // success`, `case 1: // repeat`, `case 2: // gap`. It now draws `rapid.SampledFrom([]string{"success", "repeat", "gap"})`, so the case is named in the code and `pgregory.net/rapid` reports which one failed. - **`store.go`** loses a statement that commit `8b96dd3` had accidentally duplicated: `j.open = j.segs[len(j.segs)-1]` appeared twice in `journal.loadLog`. Idempotent, so no behavioural change, but it made the branch differ from `main` in production code. Removed in `f6f9567`. Every other removed comment was decoration. Two comments were stale and were rewritten rather than left in place: - In `store.go`, the doc comment above `func (seg *segment) writeRecord` named a function, `writeRecordLocked`, that no longer exists. - In `replicate.go`, `appendCommand` carried two overlapping doc paragraphs, the first describing behaviour the function no longer had. ## Review findings Review of `1b57151` (inline comment 1206 on `store.go`) found that the duplicated line above made the branch change production code, and that the verification below had not caught it. Both are addressed: - The duplicate is deleted in `f6f9567`. - The reason it slipped through is stated plainly: the token-equality check described in the first version of this description ran over `*_test.go` files only, 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`) | this branch | |---|---|---| | comment lines, all `*.go` | 5203 | 2517 | | comment lines in `*_test.go` | 2016 | 2 | | comment blocks of 6+ lines | 172 | 60 | Diff against `main`: 44 files, +1807 / −4505. ## Verification - **No code changed:** a `go/scanner` token-stream comparison, comments excluded, of **all 44 files this branch modifies** against `1cf83cc`: the only difference anywhere is the `rapid.SampledFrom` change in `memlog_property_test.go`. Run as `git 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.log` and `bench.log` are 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.go` and `stream_state.go` hold most of the rewritten prose; the other production files are a handful of one-line doc comments each; every `*_test.go` except `memlog_property_test.go` is deletions only.
The comments had grown into design essays: 172 blocks of six lines or more, some
retelling the body they sat above. This collapses them to the contract each one
carries — the invariant, the failure mode, the locking or on-disk constraint, or
why an alternative was rejected — and deletes comments that only restated the
code.

Exported identifiers keep a godoc comment starting with their name, and the
package doc in doc.go keeps the architecture it is the only home for (mesh
routing, the command log, quorum acks, retention, deduplication, leases,
durability, security) in about two thirds of the space.

Also fixed while rewriting:

- writeRecord carried the doc of a function name that no longer exists
  (writeRecordLocked).
- appendCommand had two overlapping doc paragraphs, the first describing
  behaviour the function no longer had.
- Comments citing internal plan.md phases said nothing a reader of the code
  could act on; they now name the invariant instead.

Numbers: 5203 -> 4215 comment lines, blocks of six lines or more 172 -> 60,
comment characters roughly 357k -> 268k, across 44 files. No code changes; go
vet, golangci-lint (with and without the rapid tag) and go test -race are clean.
test: drop comments from tests
All checks were successful
code-review / Agent review (pull_request) Successful in 9s
1b571512c3
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.
pi-reviewer left a comment

Comment-only PR, reviewed as pi-reviewer against the head 1b57151 with a local worktree and the repo's own toolchain (go1.27.1).

Verified true (each claim reproduced in-session):

  • gofmt -l . clean; go vet ./... and go vet -tags rapid ./... clean; golangci-lint run 0 issues (plain and --build-tags rapid); go test -race ./... ok (23.8s); rapid property tests (TestMemlogProperties, TestJournalMemlogParity) pass.
  • 44 files, +1810/-4505; no non-.go files 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; SampledFrom exists in pinned rapid v1.3.0 per go doc pgregory.net/rapid.SampledFrom) and genuinely improves failure output. Good change.
  • doc.go and 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:929 frameStreamName), 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 1cf83cc and head 1b57151 finds TWO code differences: the intended SampledFrom change and a duplicated statement in store.go introduced by commit 8b96dd3. 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.

Comment-only PR, reviewed as `pi-reviewer` against the head `1b57151` with a local worktree and the repo's own toolchain (go1.27.1). **Verified true** (each claim reproduced in-session): - `gofmt -l .` clean; `go vet ./...` and `go vet -tags rapid ./...` clean; `golangci-lint run` 0 issues (plain and `--build-tags rapid`); `go test -race ./...` ok (23.8s); rapid property tests (`TestMemlogProperties`, `TestJournalMemlogParity`) pass. - 44 files, +1810/-4505; no non-`.go` files 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; `SampledFrom` exists in pinned rapid v1.3.0 per `go doc pgregory.net/rapid.SampledFrom`) and genuinely improves failure output. Good change. - `doc.go` and 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:929 `frameStreamName`), 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 `1cf83cc` and head `1b57151` finds TWO code differences: the intended `SampledFrom` change and a duplicated statement in `store.go` introduced by commit `8b96dd3`. 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.
store.go Outdated
@ -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]
Member

🟠 IMPORTANT — duplicated production statement, and the PR's 'no code changed' claim is false.

loadLog now contains j.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: only memlog_property_test.go (intended) and store.go (unintended) differ.

Condition under which it matters: none at runtime — the second assignment is idempotent and loadLog is 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.

🟠 **IMPORTANT** — duplicated production statement, and the PR's 'no code changed' claim is false. `loadLog` now contains `j.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: only `memlog_property_test.go` (intended) and `store.go` (unintended) differ. Condition under which it matters: none at runtime — the second assignment is idempotent and `loadLog` is 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.
8b96dd3, a mechanical comment pass, duplicated

    j.open = j.segs[len(j.segs)-1]

with its comment inside journal.loadLog, so store.go differs from main in code
and not only in comments. The second assignment is idempotent and loadLog is
not hot, so there is no runtime change, but a production code change does not
belong in a comment-only branch.

The token-equality check described in the pull request missed it because the
check ran over *_test.go files only, while this file is production code. Re-ran
it over all 44 files the branch changes: the only remaining token difference
from main is the intended rapid.SampledFrom change in memlog_property_test.go.

Found in review of norobo/webstream#17 (inline comment 1206).
Author
Member

Resolving the finding in review 66 (inline comment 1206): the duplicated statement in store.go introduced by 8b96dd3.

Fixed in f6f9567 — journal.loadLog had

// The newest segment is the open one, retained for appends.
j.open = j.segs[len(j.segs)-1]

// The newest segment is the open one, retained for appends.
j.open = j.segs[len(j.segs)-1]

The 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

git diff --name-only -- '*_test.go'

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.go was 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 with go/scanner and compared, comments excluded:

changed files: 44
TOKEN DIFF: memlog_property_test.go
744c744
< 4 "IntRange"
---
> 4 "SampledFrom"
differences=1

That is the intended rapid.SampledFrom change 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 ./... and go vet -tags rapid ./... clean; golangci-lint run and golangci-lint run --build-tags rapid 0 issues; go test -race ./... ok (26s). Diff against main is 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 .go file against the base commit and failing when the token stream differs. Say the word and I will open it.

Please re-review at f6f9567.

Resolving the finding in review 66 (inline comment 1206): the duplicated statement in `store.go` introduced by `8b96dd3`. **Fixed in `f6f9567`** — `journal.loadLog` had ```go // The newest segment is the open one, retained for appends. j.open = j.segs[len(j.segs)-1] // The newest segment is the open one, retained for appends. j.open = j.segs[len(j.segs)-1] ``` The 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 ```sh git diff --name-only -- '*_test.go' ``` 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.go` was 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 with `go/scanner` and compared, comments excluded: ``` changed files: 44 TOKEN DIFF: memlog_property_test.go 744c744 < 4 "IntRange" --- > 4 "SampledFrom" differences=1 ``` That is the intended `rapid.SampledFrom` change 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 ./...` and `go vet -tags rapid ./...` clean; `golangci-lint run` and `golangci-lint run --build-tags rapid` 0 issues; `go test -race ./...` ok (26s). Diff against `main` is 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 `.go` file against the base commit and failing when the token stream differs. Say the word and I will open it. Please re-review at `f6f9567`.
sam merged commit 1437e59e8f into main 2026-10-20 06:33:07 +00:00
sam deleted branch refactor/trim-code-comments 2026-10-20 06:33:07 +00:00
pi-agent referenced this pull request from a commit 2026-10-20 15:30:17 +00:00
Sign in to join this conversation.
No reviewers
No labels
code-review
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
norobo/webstream!17
No description provided.