From e58b54637e3a718d576d7178d17fb874447fe764 Mon Sep 17 00:00:00 2001 From: Bob Luppes Date: Sat, 12 Sep 2026 20:03:17 +0200 Subject: [PATCH] docs: add CLAUDE.md with rules on comments and public API docs Adds guidance for Claude Code sessions: comments should only call out non-obvious rationale or design choices, and public API documentation comments should never leak implementation details. Co-Authored-By: Claude Sonnet 5 --- CLAUDE.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..170d7f24 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,5 @@ +# Comments + +Only use comments to call out non-obvious rationale or design choices (e.g. why a particular approach was taken, a workaround for a specific limitation, or a subtle invariant) — not to restate what the code already makes clear. Prefer solutions that are self-documenting through clear names and proper abstraction instead of relying on comments to explain what the code does. + +Never leak implementation details in documentation comments on public APIs. Document what a public API does and how to use it, not how it is implemented internally — internal details belong in the implementation, not in the public-facing doc comment.