docs(claude): add the deletion test for code comments#384
Open
etrobert-bot wants to merge 1 commit into
Open
Conversation
Sharpen the comment-proportionality rule with an applyable test: cut a comment if it only restates what the code, filename, or option names already convey, and don't narrate where or how code is wired up (that's greppable, rots, and belongs in the PR). The existing rule was framed around length and historical narrative, which let restate-the-code and describe-the-wiring comments slip through. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
etrobert-bot
force-pushed
the
docs/comment-deletion-test
branch
from
ef6620a to
3654ce5
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
1 participant
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.
What
Sharpen the existing comment-proportionality rule in the global CLAUDE.md with an applyable test:
Why
The existing rule ("keep comments proportional… state only the single non-obvious point… leave narrative for the commit/PR") is framed around length and its narrative examples are historical (root-cause chains, incident history). That let two other failure modes slip through in a recent module:
The deletion test turns "is this non-obvious?" from a judgment call into a procedure, and the
e.g.keeps the one example illustrative rather than an exhaustive list to rules-lawyer against.Scope: global CLAUDE.md only — general comment hygiene, not a repo-specific convention, so it isn't duplicated into the project file.
🤖 Generated with Claude Code