project-commentslisted

# Code comments ## Principle A comment earns its place only if it records something a competent reader cannot recover from the code, its tests, or `git log`. You pay for narration on every future read. The default is no comment. The code says what it does. The test says what it guarantees. The commit message says why it changed. A comment covers the fourth thing: a constraint that is invisible at the call site and expensive to rediscover. ## The budget | Length | Bar it must clear | |---|---| | 0 lines | Default. | | 1–2 lines | A non-obvious constraint, stated flatly. | | 3–5 lines | Two interacting constraints, or a rejected alternative that a reader would otherwise retry. | | 6+ lines | Almost always wrong. Move it to the commit message or the PR body. | At a sixth line, stop. Ask what the reader must know **at this line of code** to avoid breaking something. Write only that. ## Keep Keep a comment that records an invisible constraint: - Ordering or coupling that the type system cannot express (*"must run first; it calls `EntityManager::clear()` as it iterates"*) - Concurrency and transaction boundaries - Why you did not use the obvious approach, when a reader would otherwise try it and revert your work - External contracts you do not control, such as an API's undocumented behaviour ## Cut Cut what the reader recovers from elsewhere: - A restatement of what the next line does - A tutorial on framework behaviour; link the concept instead - The investigation be