State the comment bar in CONTRIBUTING - #9
Open
tony wants to merge 1 commit into
Open
Conversation
why: The guidance was "comments explain why, not what. The surrounding code is the reference for density and idiom." Both halves fail a contributor. Why-not-what is not absolute — a dense algorithm earns a sketch of what it does — and pointing at the surrounding code is circular now that the surrounding code is what a sweep just corrected. Neither half says when to delete, which is the decision most often being made. what: - State the bar a comment has to clear, the ceiling, and the cases that are always deleted - Note that XML documentation is judged by caller value instead, and that CS1591 makes it a build error to omit - Link AGENTS.md, which carries the full policy and its three gates
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.
Follow-up to #8, which corrected 172 comments against the policy in
AGENTS.md. The contributor guidance did not describe the bar those changes were held to.It read:
Both halves misdirect. "Why, not what" is not absolute —
AGENTS.mditself keeps a sketch of what a dense algorithm does when the local operations do not reveal the whole. And pointing at the surrounding code as the reference for density is circular when the surrounding code is what needed correcting: the sweep found blocks running six to ten lines against a stated one-to-two line ceiling, so a contributor matching what they saw would have reproduced the defect.Neither half says when to delete, which is the decision most often being made.
What replaces it
CS1591makes omitting it a build error in the published projectsAGENTS.md, which carries the full policy and its three gatesDocumentation only. No code changes.