L04 Documenting Why Not What

title: "Documenting Why, Not What — The Most Important Commenting Principle" weight: 4 description: "Learn the most important commenting principle: document why code exists, not what it does. Master techniques for explaining intent, trade-offs, and design decisions while avoiding comments that restate the obvious." date: 2026-06-28 lastmod: 2026-06-28 tags: [technical-writing, code-comments]

The most important principle of code commenting is to document why the code exists, not what it does. The code itself shows what happens. Comments should explain why it happens that way.

In this lesson, you will learn how to apply this principle consistently and avoid common violations.

## What You'll Learn

You will distinguish what from why in code comments, write comments that explain intent and decisions, and avoid comments that restate the code.

## Why It Matters

Comments that restate the code add noise without value. Comments that explain intent add value that cannot be derived from reading the code.

## Real-World Use

DodaTech enforces the why-not-what rule in code reviews. Comments that restate the code are flagged and removed.

```mermaid
flowchart LR
  A[Code] --> B{Comment Needed?}
  B --> C[What is obvious]
  B --> D[Why is not obvious]
  D --> E[Write Why Comment]
  C --> F[No Comment Needed]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

What vs Why

The code shows what it does. i += 1 increments i by 1. A comment saying # Increment i by 1 adds no information.

The code does not show why it does it. # Batch size of 10 keeps us under the API rate limit explains why 10 was chosen.

The code does not show what alternatives were considered. # We chose streaming over bulk compression to handle large files explains a design decision.

# BAD: Documents what (code already shows this)
# Add the file to the compression queue
queue.append(file)

# GOOD: Documents why (code cannot show this)
# Read files in 64 KB blocks to limit memory usage.
# File sizes can exceed available RAM by 100x or more,
# so streaming is the only viable approach.
BLOCK_SIZE = 64 * 1024

Intent Over Mechanics

Comments should communicate the developer's intent. Why was this approach chosen? What problem does this solve?

If you find yourself explaining mechanics, stop and consider whether the code could be clearer. Clear code needs fewer mechanical comments.

Intent comments help future maintainers make good decisions. When they know why something was done, they can decide whether to change it.

# Intent comment: Explains the goal
# We limit parallel compression to 4 workers because benchmarks showed
# diminishing returns beyond 4 concurrent operations on standard SSDs.
# Higher counts increase disk contention without improving throughput.
MAX_WORKERS = 4

Common Mistakes

1. Restating the Code

Every comment that paraphrases what the code does without adding context.

2. Explaining Language Syntax

Commenting on language features the reader should already know.

3. Documenting the Obvious

Comments on trivial operations that any developer would understand.

4. No Intent Documentation

Code that does something unexpected without explaining why.

5. Apologizing in Comments

Writing Sorry this is complex comments instead of refactoring.

6. Documenting Workarounds Without Context

A workaround for a third-party bug without mentioning the bug or version.

7. Assuming the Reader Knows Why

Writing what comments because you assume the reader shares your context.

Practice Questions

1. What is the most important commenting principle?

Document why code exists, not what it does. The code shows what happens.

2. What should a why comment include?

The reasoning behind a decision, alternatives considered, trade-offs made.

3. What is wrong with # Add the item to the list?

It restates what the code already shows. It adds no value.

4. How do you decide whether a comment is needed?

If the code cannot be misunderstood about what it does, no comment is needed. If the reasoning behind the code is not obvious, add a why comment.

5. Challenge: Find 10 comments in a codebase that document what instead of why. Rewrite each to document why the code exists.

FAQ

Mini Project

Take a source file and remove every comment that documents what instead of why. For each removed comment, verify the code is still understandable. For comments that document why, evaluate whether they could be clearer.

What's Next

Next: Inline Comments