Comment Heuristics
Identify and eliminate bad comments; write the rare good one with precision.
The Five Comment Smells
C1: Inappropriate Information — use version control for history, not comments. C2: Obsolete Comment — stale comments are worse than no comments. C3: Redundant Comment — a comment that repeats the code adds noise. C4: Poorly Written — if a comment is worth writing, write it well. C5: Commented-out Code — delete it; git has history.
When to Comment
Good comments explain WHY, not WHAT. Legal notices, non-obvious intent, public API contracts, and TODO markers are acceptable. Everything else is a sign the code needs improving, not more comments.
Code Challenge
Name each comment smell (C1–C5) before seeing the fix.
💡Key takeaway
Comments are not documentation — they are apologies. Prefer expressive code that speaks for itself.
🔧 Some exercises may still have errors. If something seems wrong, use the Feedback button (bottom-right of the page) to report it — it helps us fix it fast.
Hint: C1–C5: Inappropriate info, Obsolete, Redundant, Poorly written, Commented-out code. Delete all five ruthlessly.
✗ Your version