L03 Comment Types Single Multi Docblock

title: "Comment Types — Single-Line, Multi-Line, and Docblock Comments" weight: 3 description: "Learn the three types of code comments: single-line for brief notes, multi-line for detailed explanations, and docblocks for structured API documentation. Master when and how to use each comment type in source code." date: 2026-06-28 lastmod: 2026-06-28 tags: [technical-writing, code-comments]

Code comments come in three main types: single-line, multi-line, and docblocks. Each type serves a different purpose and should be used in specific situations.

In this lesson, you will learn the characteristics of each comment type and when to use them.

## What You'll Learn

You will distinguish between single-line, multi-line, and docblock comments and choose the right type for each situation.

## Why It Matters

Using the wrong comment type reduces readability and may not work with documentation generation tools.

## Real-World Use

DodaTech enforces comment type conventions through linters. Single-line for inline explanations, docblocks for all public APIs, and block comments for design decisions.

```mermaid
flowchart LR
  A[Comment Types] --> B[Single-Line]
  A --> C[Multi-Line]
  A --> D[Docblocks]
  B --> E[Brief Notes]
  C --> F[Design Rationale]
  D --> G[API Documentation]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Single-Line Comments

Single-line comments start with // in many languages or # in Python and shell. Use them for brief explanations on a single line.

Place single-line comments on the line above the code they explain, not at the end of a line. End-of-line comments are harder to read and often wrap.

Use single-line comments for quick notes about why a specific approach was taken or what a variable represents when the name is not enough.

# Single-line comment explaining why
# Use ThreadPoolExecutor for I/O-bound compression tasks
from concurrent.futures import ThreadPoolExecutor

# Bad: end-of-line comment
x = x + 1  # This is obvious

Multi-Line Comments

Multi-line comments use /* */ in many languages or triple quotes in Python. Use them for longer explanations that span multiple lines.

Use multi-line comments for design decisions, algorithm explanations, and architecture notes that need more space than a single line.

Multi-line comments should be reserved for important context. If you need more than three lines, consider whether the code could be clearer.

# Multi-line block comment explaining a design decision
# Compression Pipeline Architecture
# =================================
# The pipeline uses streaming to handle files of any size.
# Each stage reads from the previous stage's output.
# This design prevents OOM errors for large files.

Docblocks

Docblocks are structured comments that document the interface of functions, classes, and modules. They follow a specific format that documentation generators can parse.

Docblocks should include a description, parameter documentation, return value documentation, and examples. Some formats support type annotations and cross-references.

Every public API should have a docblock. Private functions may have simpler docblocks if their purpose is not obvious.

def compress_file(input_path: str, output_path: str = None) -> dict:
    """Compress a file using the default algorithm.

    Args:
        input_path: Path to the file to compress.
        output_path: Optional output path.

    Returns:
        dict with input_size, output_size, ratio, time_ms.

    Raises:
        FileNotFoundError: If input_path does not exist.
    """

Common Mistakes

1. Using Single-Line for Multi-Sentence Explanations

A single-line comment that wraps to multiple lines. Use multi-line comments for longer text.

2. No Docblocks on Public APIs

Functions used by other modules without docblocks. Consumers must read the implementation.

3. Docblocks on Private Functions Only

Applying strict docblock rules to internal helpers but not public APIs. Public APIs need docblocks most.

4. Inconsistent Docblock Format

Mixing parameter documentation styles. Choose a format and use it everywhere.

5. Over-Commenting Simple Code

Single-line comments on every line. The code should speak for itself.

6. Docblocks Without Descriptions

Only parameter documentation without explaining what the function does.

7. Wrong Comment Syntax

Using // for docblocks or using docblock syntax for inline comments.

Practice Questions

1. What are the three types of code comments?

Single-line, multi-line, and docblocks.

2. When should you use single-line comments?

For brief explanations on a single line above the code they describe.

3. When should you use multi-line comments?

For design decisions, algorithm explanations, and architecture notes that need more space.

4. When should you use docblocks?

For documenting the interface of public functions, classes, and modules.

5. Challenge: Find examples of all three comment types in a codebase. For each, evaluate whether the correct type was used. Fix any that use the wrong type.

FAQ

Mini Project

Audit a source file for comment type usage. Identify comments that use the wrong type. Fix docblocks that should be inline comments. Convert inline comments that need more space to multi-line comments.

What's Next

Next: Documenting Why, Not What