Repository navigation
chore(lint): enforce comment shape and docs - #454
Merged
Merged
Conversation
Comments had drifted into long blocks that restate the code, and the rules in AGENTS.md were not enforced, so each review repeated the same corrections. Add two tsk linters. commentshape limits a comment to one summary line, optionally followed by a blank line and two lines of explanation. privatedoc rejects doc comments on unexported functions under 20 lines, which should be clear from their name and body. Drop the revive exclusion that hid undocumented exported declarations, so the rule that public declarations are always documented is enforced too. Bring the codebase into line: shorten or remove the existing comments and document the exported declarations that had none. Only comments change, apart from whitespace. Linter fixtures under testdata are separate modules holding deliberately malformed comments, so `just fmt` now skips them. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
alecthomas
marked this pull request as ready for review
November 17, 2026 07:59
alecthomas
requested review from
jrobotham-square
and removed request for
a team
November 17, 2026 07:59
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
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.
Comments in this codebase had drifted into long blocks that restate the code, and the comment rules in
AGENTS.mdwere not enforced. Each review ended up repeating the same corrections, most recently on #453. This change turns those rules into linters and brings the existing code into line, so the rules hold without anyone having to remember them.The approach is two new
tsklinters plus one config change:commentshapelimits every comment to one summary line, optionally followed by a blank comment line and up to two lines of explanation. Directive lines such as//nolint:x,//go:buildand// #nosecdo not count. Both limits are configurable.privatedocrejects a doc comment on an unexported function under 20 lines, since those should be clear from their name and body. A comment that explains why can be kept with//nolint:privatedoc // <reason>on thefuncline.The rest of the diff is the cleanup those rules required: about 570 comments shortened, a small number deleted where they only restated the code, and doc comments added to the 162 exported declarations that had none. Only comments change, apart from whitespace. No
//nolint:commentshapewas needed.Two things are worth a reviewer's attention:
Tiered.OpenandstatAndHeadersininternal/cache,ParallelGetandOpenGitSnapshotParallelinclient,Repackininternal/gitclone, andServeHTTPininternal/strategy/handler.config.Load, the HCL example onHostConfig, and the metadata storage note onNewS3.just fmtnow skips paths undertestdata/, because the linter fixtures are separate modules that hold deliberately malformed comments.🤖 Generated with Claude Code