Files
agent-skills/claude-md/code-comments.md
T
naps62 2f7f512cec fix: exempt doc comments from the code-comment budget
Rustdoc, JSDoc, NatSpec and docstrings document a surface for callers and
are read by tooling — NatSpec ends up in contract metadata. The rule read
as an instruction to delete them, and the linter blocked a legitimate
rustdoc block.

Also: plain block comment bodies were never linted (no per-line marker),
and a literal double-star in a code span was flagged as bold.

Merges the landmine and MUST categories, which said the same thing.
2026-08-01 14:16:48 +00:00

1.1 KiB

paths
paths
**/*.{ts,tsx,js,jsx,mjs,cjs,py,rs,go,sol,sh,bash,zsh,kt,rb,lua,zig,nix,ex,yaml,yml,toml}

Code comments

Budget: 1-3 lines. Write one only when an agent with the repo and thirty seconds of grep would still get it wrong. That means one of:

  • something that breaks silently — no test catches it, or a caller can break it from outside
  • a fact not in the repo (deployed bytecode, chain quirk, library bug)
  • a unit or epoch the type cannot carry (wei, ms, 18-dp)

Good:

// MUST read lastGoodPrice before fetchPrice — same eth_call state.

Everything else: delete. Design rationale and rejected alternatives go in docs/; leave a path. History is in git. No emphasis; ALL-CAPS only for MUST / NEVER.

Deleting a comment is cheap and reversible. When unsure, delete.

Doc comments are not this

Rustdoc ///, JSDoc /** */, Solidity NatSpec @notice/@dev, Python docstrings: different genre, budget does not apply. They document a surface for callers who cannot see the body, and tooling reads them — NatSpec ends up in contract metadata. Follow the language's convention, and never strip them to satisfy the budget above.