Skip to content

State the comment bar in CONTRIBUTING - #9

Open
tony wants to merge 1 commit into
masterfrom
docs/contributing-comment-policy
Open

State the comment bar in CONTRIBUTING#9
tony wants to merge 1 commit into
masterfrom
docs/contributing-comment-policy

Conversation

@tony

@tony tony commented Aug 16, 2026

Copy link
Copy Markdown
Contributor

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:

Comments explain why, not what. The surrounding code is the reference for density and idiom.

Both halves misdirect. "Why, not what" is not absolute — AGENTS.md itself 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

  • the bar a comment has to clear, in terms of what the code, types, assertions and tests do not already carry
  • the ceiling, and what it means when a comment exceeds it
  • the categories that are always deleted — narration, restatement, excuses, hand-tracked values — and the tiebreak toward deletion
  • that XML documentation is judged the other way round, by caller value, and that CS1591 makes omitting it a build error in the published projects
  • a link to AGENTS.md, which carries the full policy and its three gates

Documentation only. No code changes.

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
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