L05 Inline Comments

title: "Inline Comments — Explaining Non-Obvious Decisions in Code" weight: 5 description: "Learn how to write effective inline comments that explain non-obvious decisions in source code. Master inline comment placement, content, and style for documenting unexpected behavior and design choices." date: 2026-06-28 lastmod: 2026-06-28 tags: [technical-writing, code-comments]

Inline comments are brief annotations placed directly in code to explain non-obvious decisions. They are the most common type of comment and the most frequently misused. Effective inline comments save hours of confusion.

In this lesson, you will learn how to write inline comments that actually help readers.

## What You'll Learn

You will write inline comments that explain non-obvious decisions, place them correctly, and avoid common inline comment mistakes.

## Why It Matters

Inline comments are the first thing developers read when trying to understand code. Good inline comments make code approachable.

## Real-World Use

DodaTech code reviews specifically check that inline comments explain non-obvious decisions. Comments that state the obvious are flagged for removal.

```mermaid
flowchart LR
  A[Inline Comment] --> B{Non-Obvious?}
  B -->|Yes| C[Keep and Explain]
  B -->|No| D[Remove]
  C --> E[Helps Reader]
  D --> F[Adds Noise]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

When to Use Inline Comments

Use inline comments when the code does something unexpected. If a reader would pause and wonder why this is here, add an inline comment.

Use inline comments for workarounds. If you are working around a bug in a dependency, document the bug and the workaround.

Use inline comments for performance optimizations that make code less readable. Explain why the optimization matters.

Do not use inline comments for obvious operations. The code should speak for itself.

# Good inline comment: Explains non-obvious decision
# Use ThreadPoolExecutor instead of ProcessPoolExecutor because
# compression is I/O-bound, not CPU-bound. Threading avoids the
# overhead of process forking while still achieving parallelism.
from concurrent.futures import ThreadPoolExecutor

# Bad inline comment: Obvious
# Import the os module
import os

Inline Comment Placement

Place inline comments on the line above the code they explain. End-of-line comments are harder to read and often cause line-wrapping issues.

Keep inline comments short. One or two sentences. If you need more, use a block comment above the code section.

Align inline comments with the code indentation. Comments at the wrong indentation level are confusing.

# Good placement: Above the code
# Limit to 4 workers to avoid overwhelming disk I/O on SSDs
with ThreadPoolExecutor(max_workers=4) as executor:
    ...

# Bad placement: End of line (hard to read)
with ThreadPoolExecutor(max_workers=4) as executor:  # Limit workers
    ...

Common Mistakes

1. Stating the Obvious

Comments that repeat what the code clearly shows.

2. End-of-Line Comments

Comments at the end of code lines that wrap or are hard to read.

3. Too Long

Inline comments that should be multi-line block comments.

4. Assuming Context

Comments that assume the reader knows why this workaround exists.

5. Out of Date

Comments describing old behavior after code changed.

6. Commenting Every Line

Every line has a comment. The signal-to-noise ratio makes important comments invisible.

7. No Space After Comment Marker

#comment instead of # comment in languages that use #.

Practice Questions

1. When should you use an inline comment?

When the code does something non-obvious, unexpected, or requires explanation that cannot be conveyed through code alone.

2. Where should inline comments be placed?

On the line above the code they explain. Not at the end of the line.

3. How long should an inline comment be?

One or two sentences. Use a block comment for longer explanations.

4. What is the most common inline comment mistake?

Stating the obvious. Comments that restate what the code already shows.

5. Challenge: Find five inline comments in a codebase and evaluate each. Are they explaining why or restating what? Fix any that need improvement.

FAQ

Mini Project

Audit a source file for inline comments. For each comment, decide if it explains why or restates what. Remove what comments. Add inline comments for any non-obvious code that lacks explanation.

What's Next

Next: Function Comments