L08 Module Comments

title: "Module Comments — Documenting Files and Packages in Source Code" weight: 8 description: "Learn how to write module comments that document source files and packages. Master module-level docstrings covering purpose, contents, usage, and dependencies for maintainable code organization." date: 2026-06-28 lastmod: 2026-06-28 tags: [technical-writing, code-comments]

Module comments document the purpose and contents of a source file or package. They help developers understand what the module provides and how it fits into the larger codebase.

In this lesson, you will learn how to write effective module-level documentation.

## What You'll Learn

You will write module docstrings that document purpose, contents, usage, and dependencies.

## Why It Matters

Module comments are the entry point for understanding a file. They tell developers what the file contains and whether it is relevant to their task.

## Real-World Use

Every DodaTech source file starts with a module docstring. Developers can understand the file's purpose without reading its entire contents.

```mermaid
flowchart LR
  A[Module Comment] --> B[Purpose]
  A --> C[Contents]
  A --> D[Usage]
  A --> E[Dependencies]
  A --> F[Examples]
  B --> G[Quick Understanding]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Module Docstring Structure

Start with a one-paragraph description of what the module provides. What is the module's responsibility?

List the main classes, functions, and constants exported by the module. Developers can see what is available.

Include a usage example if the module provides a standalone capability.

Document external dependencies the module requires. List third-party packages and version requirements.

"""
Compression algorithms module.

This module provides compression algorithm implementations including
gzip, bzip2, and xz. Each algorithm is implemented as a strategy class
that conforms to the CompressorStrategy interface.

Main exports:
    GzipCompressor: Fast compression with gzip
    Bzip2Compressor: Better ratio with bzip2
    XzCompressor: Best ratio with xz
    create_compressor: Factory function for algorithm selection

Example:
    compressor = create_compressor("gzip")
    result = compressor.compress(b"data")

Dependencies:
    - Python 3.9+
    - bzip2 (system library for Bzip2Compressor)
    - liblzma (system library for XzCompressor)
"""

Package-Level Documentation

Packages should have an init.py with a docstring that describes the package's purpose and what submodules it contains.

Document the public API of the package. List all classes and functions that are part of the package's public interface.

Include installation or setup instructions if the package has special requirements.

"""
DodaZIP - Streaming compression library.

DodaZIP provides streaming compression for files of any size.
It supports gzip, bzip2, and xz algorithms.

Submodules:
    compressor: Main compression interface
    algorithms: Compression algorithm implementations
    utils: Utility functions for file handling

Typical usage:
    from dodazip import Compressor
    c = Compressor(algorithm="gzip", level=6)
    result = c.compress_file("data.csv")
"""

Common Mistakes

1. No Module Docstring

Files without any documentation. Developers must open the file to understand it.

2. One-Line Docstring Only

Too brief to be useful. # Compression module does not tell what is in the module.

3. Outdated Module Documentation

Module docstring listing classes that no longer exist or describing old behavior.

4. No Export List

Module docstring without listing what the module exports. Developers must read the file.

5. No Dependencies Listed

External dependencies not documented. Developers cannot tell what is needed.

6. Private Details in Module Docstring

Internal implementation details belong in inline comments, not module docstrings.

7. Missing Usage Example

Module docstring without an example. Developers must read multiple functions to understand usage.

Practice Questions

1. What should a module docstring include?

Purpose, main exports, usage example, and dependencies.

2. Why include an export list in the module docstring?

Developers can see what is available without reading the entire file.

3. Why document dependencies at the module level?

Developers need to know what third-party packages are required to use the module.

4. What is a package-level docstring?

A docstring in init.py that describes the package's purpose and submodules.

5. Challenge: Write a module docstring for a module you use or maintain. Include purpose, exports, usage example, and dependencies.

FAQ

Mini Project

Audit a codebase's module documentation. Find three modules without docstrings or with incomplete docstrings. Write complete module docstrings for each including purpose, exports, usage example, and dependencies.

What's Next

Next: TODO, FIXME, and HACK Comments