The Failure of Expression
A comment is an apology. Every time you write one to explain confusing code, you've failed to write clear code. Comments don't get compiled — they rot. The code changes, the comment doesn't, and now it's a lie. The goal: express intent through names and structure, not prose.
Comment compensates for bad name
int d; // elapsed time in daysName reveals intent
int elapsedDays;// ✗ Bad
function check(u):
// if admin and active
if u.r == "a" and u.s == 1:
return true
return false
// ✓ Good — no comment needed
function canAccessAdminPanel(user):
return user.role == "admin" and user.isActiveQuality Comments
Some comments earn their place. Legal notices (copyright). Explanations of intent — why a decision was made, not what the code does. Warnings of consequences ("Don't remove — this is a workaround for a known JVM bug"). Clarification of complex regex or algorithm that can't be simplified further.
// ✓ Legal — required by org policy
// Copyright (c) 2024 CleanKata Inc. MIT License.
// ✓ Intent — explains *why*, not *what*
// Using bubble sort intentionally — the data is almost always sorted
// and nearly sorted arrays run in O(n). Benchmarks in /docs/sort-perf.md
function sortReadings(readings):
bubbleSort(readings)
// ✓ Warning
// Don't call this more than once per request.
// The payment provider charges per token generation.
function generatePaymentToken(orderId):
...The Catalog of Noise
Redundant comments repeat what the code already says. Mandatory Javadoc on trivial getters is noise — /** Returns the name. */ getName() tells you nothing new. Commented-out code is the worst: it implies something important, but nobody knows if it's safe to delete. Delete dead code — git history remembers it.
Noise comments
// Increment counter
counter = counter + 1
function getName():
// Returns the name.
return name
// old_total = cart.items * price
// if discount: old_total *= 0.9
total = cart.calculateTotal()Delete it — git remembers
counter = counter + 1
function getName():
return name
total = cart.calculateTotal()Code Challenge
Replace Comments With Code — every comment in this function is a smell.
Key takeaway
The best comment is a good name. The second best is no comment at all. Write code that documents itself.