Why Comment — The Purpose and Value of Code Documentation

In this tutorial, you will learn about Why Comment. We cover key concepts, practical examples, and best practices to help you master this topic.

Understanding why we comment code helps you decide when to invest time in writing comments and what type of comment to write. Comments serve multiple purposes beyond explaining code behavior.

In this lesson, you will learn the strategic reasons for commenting code and how each purpose benefits your team.

What You'll Learn

You will understand the five strategic purposes of code comments and apply the right type of comment for each purpose.

Why It Matters

Knowing why you are writing a comment helps you write better comments. Each purpose requires a different style and level of detail.

Real-World Use

DodaTech uses a comment decision framework that maps comment types to purposes. Developers use the framework to decide whether and how to comment.

flowchart LR
  A[Why Comment?] --> B[Explain Intent]
  A --> C[Document Decisions]
  A --> D[Support Review]
  A --> E[Aid Maintainability]
  A --> F[Enable Automation]
  B --> G[Better Code]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Five Purposes of Comments

Explain intent when the code's purpose is not obvious from the code itself. Why does this function exist? What problem does it solve?

Document decisions that future maintainers need to understand. Why was approach A chosen over approach B? What trade-offs were considered?

Support code review by explaining why something was done a certain way. Reviewers can verify the reasoning matches the code.

Aid maintainability by providing context for future changes. A new developer can understand the code without asking the original author.

Enable automation through docstrings that documentation generators parse. This creates API documentation without additional effort.

# Purpose: Explain intent
# This function calculates a compression ratio that accounts for
# metadata overhead. Standard ratio calculations underestimate
# storage requirements for small files.

def adjusted_ratio(input_size: int, output_size: int) -> float:
    """Calculate compression ratio including metadata overhead."""
    overhead = 512  # File system block size
    return (output_size + overhead) / (input_size + overhead)

The Cost-Benefit of Comments

Comments cost time to write and maintain. Every comment must be updated when the code changes.

Comments benefit future maintainers. Well-written comments reduce the time to understand and modify code.

Invest comments where the cost is lowest and benefit is highest. Public APIs need docstrings. Complex algorithms need inline comments. Obvious code needs no comments.

# High benefit, low cost: Public API docstring
def public_function(param: str) -> int:
    """Process the parameter and return a result. This is the main entry point."""
    ...

# Low benefit, high cost: Comment on obvious code
x = x + 1  # This is obvious, comment adds nothing

Common Mistakes

1. Commenting for No Reason

Adding comments because policy requires them without considering whether they add value.

2. Commenting Everything

Treating comments as mandatory for every line of code. Selective commenting is more effective.

3. Ignoring Future Readers

Writing comments for yourself in the present. Write for a developer who has never seen this code.

4. Duplicating Documentation

Comments that repeat what is in the project documentation. Link to docs instead.

5. Assuming Shared Context

Comments that reference knowledge only the original developer has.

6. No Comment on Risky Code

Complex or fragile code without explanation of why it is risky.

7. No Comment on Workarounds

Code that works around a third-party bug without documenting the workaround.

Practice Questions

1. What are the five purposes of code comments?

Explain intent, document decisions, support review, aid maintainability, and enable automation.

2. What is the cost-benefit trade-off of comments?

Comments cost time to write and maintain. They benefit future maintainers by reducing understanding time.

3. Where should you invest commenting effort?

Public APIs, complex algorithms, non-obvious decisions, risky code, and workarounds.

4. Who are you writing comments for?

Future maintainers who have never seen this code. Write for them, not for your current self.

5. Challenge: For each of the five purposes, find or write an example comment from a real codebase. Explain why each comment serves its purpose.

FAQ

Mini Project

Select a source file from your codebase. For each comment, identify its purpose using the five-purpose framework. Remove comments that serve no purpose. Add comments where a purpose is missing.

What's Next

Next: Comment Types