The Necessary Evil of Comments

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.

int d; // elapsed time in days

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.isActive

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):
    ...

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.

// 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()

counter = counter + 1

function getName():
    return name

total = cart.calculateTotal()

Replace Comments With Code — every comment in this function is a smell.