Code Commenting (BlendAI)

Goal

Default to zero comments. You earn each one. No comment is the resting state of a line — including the lines you just changed. Add one only when you have something real the code can't say: a why, a gotcha, an invariant, a non-obvious trade-off. If you're hunting for a reason to comment, that's the signal to stop.

When a comment is earned it explains why, what is non-obvious, or what future-me would miss. The code explains what. Names + types do the heavy lifting; comments fill the gaps — and most code has no gap.

Hard rules

1. Never narrate obvious code. No // Import the module, // Loop over items, // Return result. If the line is self-evident from its identifiers, no comment. Changing a line is not a reason to comment it.
2. Why over what. A comment must add context the reader can't get from reading the code: policy, gotcha, invariant, trade-off, history, link.
3. No stacking, no drift. One comment per thing, max — if two lines explain the same block, cut one. A comment sits on the exact line it describes; a note that floats above unrelated code (a // Cast… above a plain assignment) is worse than none.
4. Em-dashes — not -- or : inside comments when joining clauses.
5. TODOs uppercase, own line: // TODO: handle expired tokens. Never inline mid-sentence.
6. Fix what's wrong, don't pad what's bare. When editing, correct or delete stale/wrong comments you pass. Missing comments on otherwise-clear code are not a defect — leave them.