commentslisted

# Comments — the ones worth keeping - **Can:** add, rewrite and delete comments in code you are already touching. - **Must:** make every comment say something the code does not, at a different level than the code; delete a comment that repeats its line. - **Cannot:** use a comment to excuse code that should be clearer, and cannot leave a comment that has stopped being true. A comment costs a reader's attention every time the file is opened, forever. It earns that by carrying something the code cannot carry. Most comments do not, which is why deleting is as much of this skill as writing. ## The test, before you write one > **Does this say something the code does not, at a different level than the code?** Ousterhout's formulation, and the sharpest tool here: a comment adds value at a **lower** level than the code (precision — units, bounds, what null means) or a **higher** level (intuition — what this is for, what it guarantees). *A comment at the same level as the code repeats the code, and is worthless.* ```js i += 1; // increment i by one ← same level. Delete. i += 1; // skip the BOM ← higher level. Keep. const t = 15000; // ms, not seconds ← lower level. Keep. ``` If the answer is no, you have two options and only two: **delete it**, or **make the code clearer** so the comment is unnecessary. A comment is not a way to pay for a confusing name. ## "Why, not what" — and where