From 6ec45db03bae9cf571a68e39ae8a6c82a95ec643 Mon Sep 17 00:00:00 2001 From: Michael Mayer Date: Sun, 17 May 2026 09:21:53 +0000 Subject: [PATCH] Rules: Reorder comment-rule bullets and link real paths Move the 'leave it out / multi-paragraph comments belong elsewhere' clause ahead of the indent-examples bullet so the priority order reads high-to-low, and point the off-source destinations at the real specs/ directory and README.md files instead of generic prose. --- .claude/rules/code-comments.md | 2 +- AGENTS.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.claude/rules/code-comments.md b/.claude/rules/code-comments.md index 6cffa4408..fa294935a 100644 --- a/.claude/rules/code-comments.md +++ b/.claude/rules/code-comments.md @@ -5,7 +5,7 @@ Doc comments for packages and exported identifiers must be complete sentences th A doc comment is **required** for every function (including unexported helpers), as well as for every non-trivial Vue `methods:` / `computed:` / watcher: - Keep comments **compact** and default to one line for WHAT in the format `// Name does X.`. Skip trivial getters (`isOpen: () => this.open`). - Add up to three follow-up lines (`// …`) only when the WHY is non-obvious: a hidden invariant, a workaround that would otherwise be undone by a future cleanup, a contract a reader can't infer from the code. +- If readers can derive the WHY from the function body or a nearby line, leave it out. Multi-paragraph comments belong in `specs/`, package `README.md` files, or issue descriptions — never in the source itself. - For short examples in comments, indent code instead of using backticks. -- If readers can derive the WHY from the function body or a nearby line, leave it out. Multi-paragraph comments belong in specifications, package README files, or issue descriptions — never in the source itself. > **Don't include in code comments:** Issue / PR numbers, "previously…" history, alternatives considered, what the function used to do, references to old commits, names of subsequent reviewers, or any narrative that names the change rather than the steady-state behavior. That context belongs in commit messages, specs, or handover notes. diff --git a/AGENTS.md b/AGENTS.md index c47b7707e..d59c3681b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -111,8 +111,8 @@ Doc comments for packages and exported identifiers must be complete sentences th A doc comment is **required** for every function (including unexported helpers), as well as for every non-trivial Vue `methods:` / `computed:` / watcher: - Keep comments **compact** and default to one line for WHAT in the format `// Name does X.`. Skip trivial getters (`isOpen: () => this.open`). - Add up to three follow-up lines (`// …`) only when the WHY is non-obvious: a hidden invariant, a workaround that would otherwise be undone by a future cleanup, a contract a reader can't infer from the code. +- If readers can derive the WHY from the function body or a nearby line, leave it out. Multi-paragraph comments belong in `specs/`, package `README.md` files, or issue descriptions — never in the source itself. - For short examples in comments, indent code instead of using backticks. -- If readers can derive the WHY from the function body or a nearby line, leave it out. Multi-paragraph comments belong in specifications, package README files, or issue descriptions — never in the source itself. > **Don't include in code comments:** Issue / PR numbers, "previously…" history, alternatives considered, what the function used to do, references to old commits, names of subsequent reviewers, or any narrative that names the change rather than the steady-state behavior. That context belongs in commit messages, specs, or handover notes.