Comments Are Deodorant

Kevlin Henney: "Comments are deodorant for stinky code." A comment that exists to make confusing code bearable is not documentation — it's a mask over a defect. The defect is still there. Robert C. Martin goes further: "Comments are, at best, a necessary evil... every comment represents a failure to express ourselves in code." Don't comment bad code — rewrite it.

A comment is untyped, unexecuted, unenforced prose sitting next to code that keeps changing. Nothing about it stays true unless something forces it to. That's the whole risk profile: every comment you write is a claim that will silently rot the first time the code around it changes and nobody remembers to update the sentence.

The litmus test