Skip to content

chore(lint): enforce comment shape and docs - #454

Merged
alecthomas merged 1 commit into
mainfrom
aat/lint-private-helper-docs
Nov 17, 2026
Merged

alecthomas merged 1 commit into
mainfrom
aat/lint-private-helper-docs

Conversation

@alecthomas

Copy link
Copy Markdown
Collaborator

Comments in this codebase had drifted into long blocks that restate the code, and the comment rules in AGENTS.md were 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 tsk linters plus one config change:

  • commentshape limits 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:build and // #nosec do not count. Both limits are configurable.
  • privatedoc rejects 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 the func line.
  • The revive exclusion that hid "exported X should have comment" is removed, so the existing rule that public declarations are always documented is now enforced.

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:commentshape was needed.

Two things are worth a reviewer's attention:

  • Shortening lost some detail. The comments most affected are Tiered.Open and statAndHeaders in internal/cache, ParallelGet and OpenGitSnapshotParallel in client, Repack in internal/gitclone, and ServeHTTP in internal/strategy/handler.
  • A few comments were corrected, not just shortened, because the old text no longer matched the code: the interceptor ordering in config.Load, the HCL example on HostConfig, and the metadata storage note on NewS3.

just fmt now skips paths under testdata/, because the linter fixtures are separate modules that hold deliberately malformed comments.

🤖 Generated with Claude Code

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
alecthomas marked this pull request as ready for review November 17, 2026 07:59
@alecthomas
alecthomas requested a review from a team as a code owner November 17, 2026 07:59
@alecthomas
alecthomas requested review from jrobotham-square and removed request for a team November 17, 2026 07:59
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-17T08:01:19.441224Z dccd554 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@alecthomas
alecthomas merged commit 5517be7 into main Nov 17, 2026
7 checks passed
@alecthomas
alecthomas deleted the aat/lint-private-helper-docs branch November 17, 2026 08:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant