Introduction to Code Commenting — Why Comments Matter in Software Development

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

Code comments are explanatory text embedded in source code that helps humans understand what the code does and why it does it. Good comments make code maintainable. Bad comments make code harder to maintain than no comments at all.

In this lesson, you will learn the purpose of code comments and when they add value.

What You'll Learn

You will understand the purpose of code comments, distinguish between what and why comments, and recognize good and bad commenting patterns.

Why It Matters

Code is read far more often than it is written. Comments are how you communicate with future maintainers, including your future self six months from now.

Real-World Use

The DodaTech codebase has a commenting standard that reduced onboarding time for new developers from two weeks to three days. New team members could understand the code's intent without asking the original author.

flowchart LR
  A[Source Code] --> B[Comments]
  B --> C[Explain Why]
  B --> D[Document Interface]
  B --> E[Mention Trade-offs]
  C --> F[Maintainable Code]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Comments VS Code

The code tells you what happens. Comments should tell you why it happens that way.

If the code is unclear, refactor it instead of adding a comment. Clear code with good naming needs fewer comments.

Comments that restate the code add no value. i += 1 # Increment i by 1 is a waste of a line.

Comments that explain the reasoning behind a decision add value. # Use 4 workers max to avoid disk I/O saturation on SSDs.

# Bad: Restates the code
# Set the batch size to 10
batch_size = 10

# Good: Explains the reasoning
# Process in batches of 10 to stay under the API rate limit of
# 100 requests per 10 seconds (10 requests/sec = safe margin)
BATCH_SIZE = 10

The Cost of Bad Comments

Bad comments cost more than no comments. Outdated comments actively mislead future maintainers.

A comment describing old behavior while the code does something new causes bugs. Developers trust comments and may not read the code carefully.

Comments that are wrong are worse than comments that are missing. Missing comments force you to read the code carefully. Wrong comments can make you believe incorrect things about the code.

# This comment is actively dangerous if it is wrong

# This function compresses using gzip (WRONG if we switched to bzip2)
def compress_file(path: str):
    # Actually uses bzip2 now
    ...

Common Mistakes

1. Restating the Obvious

Commenting what instead of why. The code already shows what happens.

2. Outdated Comments

Comments that do not match the current code. They mislead future maintainers.

3. No Comments on Subtle Code

Code that does something unexpected without explanation. Future maintainers may break it.

4. Overcommenting

Every line commented. The signal-to-noise ratio makes it hard to find important comments.

5. Commenting Bad Code

Adding comments to explain confusing code instead of Refactoring the code.

6. Personal Comments

Adding humor, complaints, or personal notes. Professional codebases need professional comments.

7. Merge Artifacts

Comments from merged branches that no longer apply. Clean them up during review.

Practice Questions

1. What is the primary purpose of code comments?

To explain why code exists and why certain decisions were made. The code itself shows what happens.

2. What is the cost of an outdated comment?

It actively misleads future maintainers. Wrong information is worse than no information.

3. When should you refactor instead of comment?

When the code's purpose can be made clear through better variable names, function names, or structure.

4. What is the difference between a good and bad comment?

A good comment explains reasoning and trade-offs. A bad comment restates what the code already shows.

5. Challenge: Find five bad comments in open-source code. For each, explain why it is bad and how to fix it.

FAQ

Mini Project

Audit a source file from your own codebase or an open-source project. Identify every comment and categorize it as good, bad, or neutral. Rewrite the bad comments. Remove comments that restate the obvious.

What's Next

Next: Why Comment