Help Claude write fewer, better comments

CLAUDE.md

Documenting code

Docblocks go on public and exported declarations only. Write them as reference material, in the style of Hibernate or an Apache project: thorough, concise, formal, consistent. A manual, not a story.

• Open with a one-sentence summary in the third person — "Reads…", "Returns…", "Makes…" — never "This method…". Add further paragraphs only for behaviour a caller must know: transaction scope, idempotence, ordering, what is left untouched.
• Document every parameter with @param, every non-Unit return with @return, and every exception a caller can act on with @throws. A public method that can throw and says nothing about it is incomplete. @param on a type parameter documents what the type argument is for.
• Use RFC 2119 keywords for a caller's obligations (MUST be persisted), not hedged prose.
• Rationale belongs in the ADR, not the docblock. State the constraint; do not argue for it. "defs scopes the read: entity_id is unique only within an entity type" is reference material. Three sentences on why the alternative was rejected is not — link the ADR instead.
• Reference other declarations with [Name] so KDoc links them.
• Describe the code as it is, never as it changed. A docblock MUST NOT compare against previous behaviour, explain a migration, or record what a change replaced — that belongs in the commit message, which is dated and diffable. "Returns the qualified name" is reference material; "now returns the qualified name rather than the bare one" is narration.
• A docblock MUST describe its own declaration, not the pattern the declaration belongs to. If the same text would serve a sibling with the noun swapped, it documents a convention, and the convention belongs in the module README once. Leave behind only what is true of this declaration alone — and prefer nothing to a restatement.

Code MUST NOT cite ticket identifiers. Tickets carry status and dates; code carries neither, so a reference rots in place while still reading as current. State the constraint the ticket describes instead. The sole exception is an open defect a reader MUST know about to understand why code is shaped defensively; such a comment MUST name the ticket and MUST be deleted when it closes. Tickets belong in commit messages, PR descriptions, and ADRs.

This governs docblocks. Inline comments are the exception, not the norm: prefer a name, a smaller function, or a test. Where one is warranted it explains why, never what, in one or two lines.