docs(comments): drop comments that carry nothing the code does not - #140
Merged
Ilyes512 merged 1 commit intoSep 4, 2026
Merged
Conversation
The repo's convention is a comment that explains why, and most of them earn their place. These do not. Three kinds are removed. Diff narration — templateRow explaining that `Name` "was a JSON key only because it was also a heading", and executeTemplate naming the Phase 7 and Phase 8 that introduced it — records what changed, not what is. That belongs in a commit message; in the code the next reader has no idea what "was" refers to. Restatement — "Check file content." above os.ReadFile, "Build dependency graph among computed keys." above the loop that builds it, the numbered walkthrough of Execute's walk function, "validateGitHubName checks that a GitHub owner or repo name is valid." The two "copy so the caller's map is not mutated" notes in context.go say what the function doc two paragraphs up already promises. Duplication — the rationale for splitting display strings from row values was written out four times, once per site it touched. It is kept where the split is defined (Column and TableData) and the other sites point at it rather than restating it, so rewording it later is one edit and not four. Where a comment mixed a real constraint into a restatement the constraint is kept and the restatement dropped: hasEmptySegment's "conditional directory exclusion" becomes the subtree exclusion it actually means, and validate.go keeps the non-obvious half about Template.Referenced covering computed expressions. No behaviour changes, so no test or doc updates accompany this.
Ilyes512
force-pushed
the
chore/prune-unnecessary-comments
branch
from
September 4, 2026 08:45
68df26f to
b80b430
Compare
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
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.
Top of the stack on #135. Comments only — no behaviour changes, so no test or doc updates accompany it.
The repo's convention is a comment that explains why, and most of them earn their place. This prunes the ones that do not, across the stack's additions and the code that was already there.
Diff narration.
templateRowexplaining thatName"was a JSON key only because it was also a heading", andexecuteTemplatenaming the Phase 7 and Phase 8 that introduced it. That belongs in a commit message; in the code the next reader has no idea what "was" refers to.Restatement.
// Check file content.aboveos.ReadFile,// Build dependency graph among computed keys.above the loop that builds it, the numbered 1–5 walkthrough ofExecute's walk function,// validateGitHubName checks that a GitHub owner or repo name is valid., and threeTestX verifies that…comments that only spell out their own test name. The two "copy so the caller's map is not mutated" notes incontext.gosay what the function doc two paragraphs up already promises.Duplication. The rationale for splitting display strings from row values was written out four times, once per site the stack touched. It stays where the split is defined —
ColumnandTableData— and the other sites point at it rather than restating it, so rewording it later is one edit instead of four. Same for the CI-hang rationale, which now lives onprompter.cannotPromptalone.Where a comment mixed a real constraint into a restatement, the constraint is kept and the restatement dropped:
hasEmptySegment's "conditional directory exclusion" becomes the subtree exclusion it actually means, andvalidate.gokeeps the non-obvious half aboutTemplate.Referencedalready covering computed expressions.Checks
task test,go test -race,go test -tags=integration -race ./internal/cmd/...andgo buildall pass.One note: the local
task lintreports 6 pre-existingSA5011staticcheck findings ininternal/cmd/metadata_test.go, a file this PR does not touch. They reproduce identically on #135's head and CI's golangci-lint is green there, so it is local toolchain drift rather than anything introduced here.Stack created with GitHub Stacks CLI • Give Feedback 💬