lean-comments
Lean Comments
Goal
Keep the smallest amount of high-value commentary necessary to make a codebase easier and safer to understand and maintain.
The default is no comment.
A comment must preserve meaningful information that a competent maintainer cannot reasonably recover from the code, names, types, signatures, structure, tests, configuration, or nearby context.
Comments are not labels, narration, decoration, declaration summaries, change logs, or substitutes for clear code.
Reader model
Write for a competent maintainer reading the repository at HEAD months later, without access to the current conversation, prompt, diff, pull request, issue discussion, review discussion, or implementation process.
Document the durable state, contract, constraint, or rationale of the code as it exists. Do not assume the reader knows what changed, what came before, or what was discussed unless that context is deliberately preserved in a reliable project source.