Skip to content

AGENTS.md: add comment deduplication rules - #38499

Merged
DAlperin merged 1 commit into
MaterializeInc:mainfrom
DAlperin:dov/agents-comment-rules
Aug 27, 2026
Merged

AGENTS.md: add comment deduplication rules#38499
DAlperin merged 1 commit into
MaterializeInc:mainfrom
DAlperin:dov/agents-comment-rules

Conversation

@DAlperin

Copy link
Copy Markdown
Member

Extends the existing "Code comments" section of AGENTS.md with three rules distilled from a comment audit of mz_ore::pool and mz_timely_util::columnar (cleanup in #38434):

  • One owning comment per fact. Reasoning lives at the decision point, mechanism docs at the mechanism, config semantics on the public setter or constant; other sites point at the owner or say nothing. Covers the common failure of the same clause appearing near-verbatim in a module doc, a struct doc, and an inline comment, plus its corollaries: don't restate a callee's contract at call sites, and don't duplicate an assert message in a comment.
  • Budget doc-comment paragraphs by decisions. No re-arguing a decision documented elsewhere, no enumerating callers or fields, no speculative future-implementation notes, no absence-narration, no ASCII section-divider banners, no unverifiable performance color.
  • Test-doc economy. A test whose name and assert messages state the property needs no doc comment; test docs are for non-obvious setup, scenario-encoding fixtures, and multi-phase protocols.

The existing rules in the section (fluff, body narration, chronology, NOTE/TODO) are untouched; the additions only cover what the section didn't already say.

Generated with Claude Code

@DAlperin
DAlperin merged commit 52da755 into MaterializeInc:main Aug 27, 2026
8 checks passed
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.

2 participants