Codify comment layout in the Documentation Style Conventions - #419
Merged
Conversation
The Comments guidance said when to comment and how short, but never the layout of a multi-line comment, so an agent defaults to wrapped prose blocks. Add the structure rules, adopted from an operational repo's local phrasing that got it right: one sentence per line, never wrap a sentence, no block paragraphs; a continuation stays unindented while sub-topics are '# -' bullets off a lead line. Two worked examples make the continuation-vs-list distinction concrete. Fold the redundant line-length bullet into the sentence-per-line rule, and drop the 'Keep it short' bullet's own clause-splicing semicolon. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates AGENTS.md to explicitly codify the layout rules for multi-line comments so agents and contributors produce structured, consistently formatted comments rather than wrapped prose blocks.
Changes:
- Refines the existing "Keep it short" rule into clearer, sentence-based guidance.
- Adds explicit layout rules for multi-line comments (one sentence per line, continuation vs sub-topic list structure).
- Adds worked examples demonstrating continuation lines vs
-sub-topic bullets.
Comments suppressed due to low confidence (1)
AGENTS.md:161
- Similar to the bullet above, this sentence frames sub-topics as
# -bullets, which is workflow-specific. Consider describing the pattern as-bullets and using# -only as the example prefix.
Sub-topics are `# -` bullets, each elaborating a distinct item named in the lead:
The Comments section covers // languages too, so state the sub-bullet as a '-' after the comment marker (# -, // -), not the shell/YAML-specific # -. Also use a clearer adjective in the example (a diff that cannot be computed). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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.
The Comments guidance covered when to comment and how short, but never the layout of a multi-line comment - so an agent defaults to wrapped prose blocks, and comment style is a recurring conformance miss.
Adopt the structure rules from an operational repo (ESPHome-Config) whose local
Comments are structured, not prosesection got it exactly right, feeding the good phrasing up to the canonical:# -bullets hanging off a lead line;Also fold the redundant
~120 / not 80-col wrapbullet into the sentence-per-line rule (which supersedes it), and drop theKeep it shortbullet's own clause-splicing semicolon.Carried as intent via Documentation Style Conventions, so it propagates on the next AGENTS re-vendor. Once this is on
main, ESPHome-Config's local section converges to the canonical rather than staying a fork.