comment-overlap

Overview ¶

Flag comments whose content is inferable from the code they sit next to.

Usage:

go run ./scripts/comment-overlap ./internal/...
go run ./scripts/comment-overlap -threshold 0.6 -sample 25 ./...
go run ./scripts/comment-overlap -json ./internal/commands/mr/...

The signal is token coverage: a comment whose words are mostly already present in the adjacent code restates that code, so it carries no information a reader could not get from the line itself. This is a mechanical proxy for "document only what is non-obvious from the code".

Doc comments are skipped by position, using go/ast Doc fields rather than text heuristics, so idiomatic godoc on an exported symbol is never flagged for repeating its own symbol name. Only inline comments are considered.

Comment tokens are matched against code tokens after camelCase and snake_case splitting, so "clear env vars" is recognised as covered by env.RemoveVar(...).