[Code Mastery] Learn to Read What Code Won't Tell You

Reading the Hidden Intent Behind Code in Comments and Documentation

When reading code, you often wonder: “Why was it implemented this way?” Comments and documentation hold the answer, but if you don’t know how to read them properly, they’re useless. Developers must learn to read beyond simple explanations—they need to extract constraints, tradeoffs, and warnings about the future.

Understanding the Many Faces of Comments

Not all comments are created equal. Each type of comment carries a different intent.

Distinguishing header comments from inline comments

A header comment at the top of a function explains what the function does, but comments inside the function usually explain why that part is necessary. For example:

def calculate_discount(price, user_type):
    # New users don't get first-purchase discount (legal reason: see promotion terms)
    if user_type == "new":
        return price
    
    # Discount rates for existing users: VIP 20%, regular 10%
    return price * (0.8 if user_type == "vip" else 0.9)

Header comments describe the function’s contract; inline comments explain why that contract is written the way it is.

Overlooked comment types

• License comments: Copyright or license declarations at the top of files—they indicate legal constraints on code reuse, modification, and distribution.
• TODO/FIXME comments: Incomplete work or known bugs—they’re more useful when they note when and who should handle them.
• JSDoc/docstrings: Formatted comments describing types, parameters, return values, and exceptions—they enable IDE autocomplete and automatic documentation generation.

The Tension Between Self-Documenting Code and Comments

There’s a principle that good code should explain itself. Clear variable names and function names mean fewer comments are needed. But there are moments when self-documentation alone falls short:

# Bad comment: "divide x by 2"
result = x / 2

# Good comment: "convert physical pixels to logical pixels (for Apple Retina displays)"
logical_pixel = physical_pixel / 2

Variable names alone won’t tell you why you’re dividing by 2. That’s the real purpose of a comment.

Three Steps to Reading Code Intent

When comments are missing or incomplete, follow this staged strategy.

Step 1: Find intent in the code itself

Start by looking at test cases. Tests show what inputs should produce what outputs.

# Tests reveal intent
def test_discount():
    assert calculate_discount(1000, "new") == 1000  # new users: no discount
    assert calculate_discount(1000, "vip") == 800   # VIP: 20% discount

Step 2: Check Git history and issue discussions

git log -p --follow -- app/services/payment.py

When and why a file was modified reveals the reasoning behind design decisions.

commit a3f9e2c: "Remove retry logic on payment failure"
- Reason: payment gateway already handles retries; remove duplication
- Before: infinite loops caused customer complaints

Step 3: Interpret hidden constraints and tradeoffs

Some code looks inefficient because of performance, compatibility, security, or legal requirements:

# Why so complicated?
if not user.has_permission("delete") or not user.is_verified():
    # Security: prevent unverified accounts from deleting (GDPR compliance)
    log_security_event(user.id)
    raise PermissionDenied()

The Side Effect of Comments: The Danger of Outdated Comments

Comments are easier to forget to update than code. Outdated comments become toxic misinformation.

def process_order(order_id):
    # Comment: "Process order immediately"
    # Reality: added to async queue, processed 5 seconds later
    
    queue.enqueue(order_id)  # Code already changed, comment didn't

Better approach: - Trust the code first; use comments only to explain why - If a comment is wrong, don’t fix the comment—refactor the code to be clearer

Building the Habit in Practice

Every time you read comments and documentation, check three things: 1. Is this decision really necessary? (Can it be refactored?) 2. How long is this constraint valid? (Is it technical debt?) 3. Does this comment match the code? (Can I trust it?)

With these habits, you’ll be able to read the full context of an entire system from just a few lines of code.