docs: where a comment goes, and when the code should say it instead - #712
Merged
Conversation
lneto
force-pushed
the
claude_agents_comment_clarity
branch
from
August 12, 2026 14:06
288810e to
0acfae3
Compare
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
lneto
force-pushed
the
claude_agents_comment_clarity
branch
from
August 12, 2026 14:08
0acfae3 to
1db1e7f
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.
Two rules from the #693 review of a single comment.
An API-choice justification belongs on the line that makes the call, not floating above the signature; and before writing it, ask whether the call already carries the reason --
raw_cpu_ptroverthis_cpu_ptris its own comment to a kernel reader.And reaching for a comment is first a signal to reconsider clarity: a better name, a named helper, a real enum. Comment what the code cannot be made to say.