Comments Capture Design Knowledge

Comments exist to record the information in the designer's head that the code itself cannot express: intent, rationale, units, invariants, and the abstraction a module presents. Good comments describe things not obvious from the code.

Why it Matters

A large part of a design lives only in the author's mind and is lost the moment they move on. Comments are how that knowledge survives, and they make modules deep by letting callers understand an interface without reading the implementation.

Signals

• A comment restates the code ("increment i") and adds nothing.
• Readers must reverse-engineer intent or constraints that were never written down.
• Implementation details have crept into an interface comment, leaking information.

Benefits

Preserves rationale, documents the abstraction at the interface level, and reduces the cognitive load of using or changing a module. Writing comments first can also expose a bad design early, when the explanation comes out clumsy.

Risks

Comments that repeat the code add noise and rot. Comments at the wrong level (implementation detail in an interface comment) leak information. Stale comments mislead; they must change with the code.

Tensions

Conflicts with the "good code is self-documenting, comments are a smell" view. The resolution: names and structure should make the what obvious, while comments carry the why and the abstraction that code genuinely cannot encode.

Examples

An interface comment stating what a function does, its units, and its preconditions lets callers use it without reading the body. A comment explaining why an unusual approach was chosen prevents a later reader from "fixing" it back into a bug.