From af0815cd8f9581cc319f94f2c3fe39695874f961 Mon Sep 17 00:00:00 2001 From: Geoff Whatley Date: Tue, 11 Aug 2026 01:43:01 +1000 Subject: [PATCH] docs: drop the comments section from the shared partial Comment rules move to each project's own agents/project.md, where they can carry project-specific guidance such as bridges into local docs tooling. --- AGENTS.md | 14 -------------- agents/shared.md | 14 -------------- 2 files changed, 28 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e15a09f..c8c7853 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -37,20 +37,6 @@ what tooling can't check. it starts a name. File names are unaffected: kebab-case lowercases everything (`parse-cli-args.ts` exports `parseCLIArgs`). -### Comments - -- Comments that document a declaration are JSDoc blocks, always multi-line (`/**` alone, one - `*`-prefixed line per point, `*/` alone — never single-line `/** … */`), attached directly to the - declaration they describe; `//` is for statement-level commentary inside bodies. -- Comment a declaration only for what the file doesn't already show — an invariant, cross-file or - runtime behavior, or why the choice is necessary. A comment that restates the name or signature is - a defect — delete it. -- Comments describe the code as it is now — no history ("previously", "now uses"), no project state - (issue numbers, phase labels, "not wired yet"); those live in the commit message. -- Comments don't name other declarations — renames strand the reference. State the contract instead: - "callers must pass edits sorted last-to-first", not "(buildEditsFromAST's contract)". A - declaration's own parameters and signature types are fine to name. - ### Function naming Every function name starts with a prefix from the closed list below: pick from it, or extend this diff --git a/agents/shared.md b/agents/shared.md index 909b715..6ac0cd4 100644 --- a/agents/shared.md +++ b/agents/shared.md @@ -35,20 +35,6 @@ what tooling can't check. it starts a name. File names are unaffected: kebab-case lowercases everything (`parse-cli-args.ts` exports `parseCLIArgs`). -### Comments - -- Comments that document a declaration are JSDoc blocks, always multi-line (`/**` alone, one - `*`-prefixed line per point, `*/` alone — never single-line `/** … */`), attached directly to the - declaration they describe; `//` is for statement-level commentary inside bodies. -- Comment a declaration only for what the file doesn't already show — an invariant, cross-file or - runtime behavior, or why the choice is necessary. A comment that restates the name or signature is - a defect — delete it. -- Comments describe the code as it is now — no history ("previously", "now uses"), no project state - (issue numbers, phase labels, "not wired yet"); those live in the commit message. -- Comments don't name other declarations — renames strand the reference. State the contract instead: - "callers must pass edits sorted last-to-first", not "(buildEditsFromAST's contract)". A - declaration's own parameters and signature types are fine to name. - ### Function naming Every function name starts with a prefix from the closed list below: pick from it, or extend this