functional-writing-useful-commentslisted

# Writing Useful Comments ## Overview Comments exist to record what the code cannot say. Types state structure; names state meaning; neither states why a threshold is thirty days, which other module depends on this ordering, or what the caller must guarantee. Those facts exist in the author's head and are lost unless written down. The usual objections to comments are all objections to bad comments. Comments that restate the code are worthless and go stale; comments that carry information not present in the code are the difference between a module a stranger can use and one only its author can. ## When to use - Writing an exported function, type, or module - A design decision was not obvious and has a reason - Something in the code would surprise a reader - Reviewing a diff whose comments repeat the code - Designing an interface, where comments come before the code Not for: naming, which is [functional-choosing-precise-names](../functional-choosing-precise-names/SKILL.md). ## The rule A comment must contain information that is not in the code. Test any comment by deleting it and asking what was lost. If nothing, it should not exist. ```text -- worthless: the code says this -- increment the counter counter = counter + 1 -- valuable: the code cannot say this -- Thirty days, not the contractual sixty, because the payment -- provider expires authorisations at thirty and a longer window -- produces charges that always fail. authorisationWindow = Days 30 ``` ## The four e