Self-Documenting Code

The test for any comment: does it say something at the same level of abstraction as the code next to it? If yes, it duplicates the code — refactor so the code says it, then delete the comment. If it operates at a different level — more precise (units, ranges, invariants) or more abstract (intent, contract, rationale) — it carries information code cannot, and it stays.

This is not "never comment." Ousterhout's A Philosophy of Software Design is the sharp counterpoint to comment-minimalism: "comments should describe things that aren't obvious from the code" — and for interfaces, plenty isn't. The skill is telling redundant comments from load-bearing ones.

Use this skill when