.claude/rules/comments.md says default to no comments — only keep when the why is non-obvious. Claude sessions have been drifting back to over-commenting in src/ (TS) and sdk/python/ (Python): obvious restatements above well-named functions, docstrings echoing signatures, # Step 1 / "Now we…" sediment.
To do
- Sweep
src/ and sdk/python/ for comments + docstrings that fail the three tests in comments.md §2 (says nothing new / rots on refactor / removing causes no concrete wrong decision). One PR, mechanical.
- Sharpen the rule so it doesn't drift again — add a one-line pointer in
CLAUDE.md (loads every session) to .claude/rules/comments.md with "in doubt, delete."
- Python: same bar —
pyright --strict doesn't gate docstring quality. Keep contract docs (raised errors, invariants); drop signature echoes.
Keep
JSDoc / docstrings on exports that document contract (typed errors, invariants, side effects). Codegen sentinels.
.claude/rules/comments.mdsays default to no comments — only keep when the why is non-obvious. Claude sessions have been drifting back to over-commenting insrc/(TS) andsdk/python/(Python): obvious restatements above well-named functions, docstrings echoing signatures,# Step 1/ "Now we…" sediment.To do
src/andsdk/python/for comments + docstrings that fail the three tests incomments.md§2 (says nothing new / rots on refactor / removing causes no concrete wrong decision). One PR, mechanical.CLAUDE.md(loads every session) to.claude/rules/comments.mdwith "in doubt, delete."pyright --strictdoesn't gate docstring quality. Keep contract docs (raised errors, invariants); drop signature echoes.Keep
JSDoc / docstrings on exports that document contract (typed errors, invariants, side effects). Codegen sentinels.