Why Programming Legends Rarely Talked About Comments

#python#coding#programming#softwaredevelopment

The surprising truth about code clarity from Knuth, Kernighan, and the masters

When I started researching what programming legends had to say about comments, I expected to find volumes of wisdom about when, where, and how to comment code. What I found instead was... almost nothing.

Donald Knuth, the father of algorithmic analysis, barely mentioned comments in his legendary works. Grace Hopper, who invented the first compiler, focused on making programming "as close to natural language as possible" but said little about commenting that natural language. Even Brian Kernighan, co-author of the iconic C programming book, had just one famous quote about comments:

"Don't comment bad code—rewrite it."

At first, this silence puzzled me. Then I realized: the legends weren't ignoring comments—they were solving the problem that makes comments necessary.

The Real Philosophy: Self-Documenting Code

While Python's official documentation tells you the mechanics of comments (start with #, extend to end of line), the programming masters were focused on something deeper: writing code so clear that extensive commenting becomes unnecessary.

Knuth captured this perfectly when he said: "Programming is the art of telling another human being what one wants the computer to do." Notice he didn't say "commenting is the art of explaining code." He believed the code itself should be the primary form of human communication.

The Rigor Test

Here's the uncomfortable truth the legends understood:

• More comments = lack of rigor
• Fewer comments = more rigorous code

This doesn't mean comments are bad. It means that if you need extensive comments to explain what your code does, your code probably isn't rigorous enough.

Let's see this in action.

The Bad Example: Comment-Heavy Code

# Initialize counter variable to zero
count = 0

# Loop through each item in the list
for item in data:
    # Check if the item meets our condition
    if item > threshold:
        # Increment the counter by one
        count = count + 1

# Return the final count value
return count

Every line has a comment, but what do these comments actually tell us? They're just describing what the code obviously does. This is what Kernighan meant by "bad code"—code that requires commentary to be understood.

The Good Example: Self-Documenting Code

def count_items_above_threshold(data, threshold):
    """Count how many items exceed the given threshold.

    Used for filtering sensor readings above safety limits.
    """
    return sum(1 for reading in data if reading > threshold)

Notice what happened:

• The function name explains what it does
• Variable names (data, threshold, reading) are self-explanatory
• The only comment explains why we need this function (safety limits)
• The code is so clear that line-by-line comments would be redundant

The Legends' Secret Weapon: Intention-Revealing Names

Grace Hopper championed making programming accessible through natural language. She wasn't talking about comments—she was talking about the code itself reading like English.

Compare these approaches:

Comment-dependent:

# Calculate user's age from birth year
age = 2025 - birth_year

# Check if user can vote
if age >= 18:
    # Allow access to voting section
    show_voting_interface()

Self-documenting:

def calculate_age_from_birth_year(birth_year):
    current_year = 2025
    return current_year - birth_year

user_age = calculate_age_from_birth_year(birth_year)

if user_is_eligible_to_vote(user_age):
    show_voting_interface()

The second version tells a story. You can read it aloud and it makes sense to a non-programmer.

When Comments Still Matter

The legends weren't anti-comment. They understood that comments serve a crucial purpose—but not the one most people think.

Good comments explain:

• Why decisions were made
• Context that isn't obvious from code
• Warnings about edge cases

def process_payment(amount, currency="USD"):
    # Convert to cents to avoid floating-point precision issues
    # See: IEEE 754 floating-point arithmetic limitations
    amount_in_cents = int(amount * 100)

    # Rate limiting: Maximum 5 API calls per second per vendor agreement
    enforce_rate_limit()

    return payment_gateway.charge(amount_in_cents, currency)

These comments add value because they explain why the code exists, not what it does.

The Takeaway

The programming legends rarely talked about comments because they were busy solving the underlying problem: unclear code.

Their philosophy was simple:

1. Write code that explains itself
2. Use comments sparingly, for context and reasoning
3. If you need lots of comments to explain what code does, rewrite the code

This is why Kernighan's quote is so powerful. He didn't say "write better comments for bad code." He said rewrite the code.

The next time you find yourself writing extensive comments to explain your code's behavior, ask yourself: "What would Kernighan do?" The answer isn't more comments—it's clearer code.

After all, if your code needs a manual, maybe the problem isn't the documentation. Maybe it's the code.

---

Aaron Rose is a software engineer and technology writer at tech-reader.blog and the author of Think Like a Genius.