From 5f9527a8f010efcf1a2cef46569068d0526f6d31 Mon Sep 17 00:00:00 2001 From: Dan Connolly Date: Wed, 7 Oct 2026 09:46:33 -0500 Subject: [PATCH] docs-files-api: write comments for the reader, not the conversation Comments say what the code is and why in the reader's terms: no traces of the design conversation, and nothing the code already says. Generated-by: Claude Opus 5.5 --- docs-files-api/SKILL.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs-files-api/SKILL.md b/docs-files-api/SKILL.md index 1b23fe4..34a2a36 100644 --- a/docs-files-api/SKILL.md +++ b/docs-files-api/SKILL.md @@ -28,6 +28,10 @@ JSDoc placement rules (from the no docstrings; a string literal is the honest equivalent) rather than copying it or reading the script's own source. Helpers inside still get their own JSDoc. +- **Write for the reader, not the conversation:** Comments say what the + code is and why, in the reader's terms. No traces of how it came to be + (design discussions, who asked, "for now", analogies used while + deciding), and nothing the code or its shebang already says. - **External design constraints:** If a module is constrained by external contracts, standards, or off-repo design docs, add a short JSDoc note with a `@see` link to the authoritative source at the relevant entry point(s).