Docstrings

Docstrings are the primary building block of in-code documentation. You can use them to document functions, classes, methods, modules, and packages in Python. Unlike regular comments, docstrings are part of your code and are stored as runtime attributes, which means you can inspect and manipulate them programmatically.

Tools like the built-in help() function, IDEs, static type checkers, and documentation generators can read them to demonstrate how to work with your code. While static type checkers primarily rely on type annotations, docstrings can still complement type information by explaining intent and behavior.

PEP 257 contains Python’s official conventions for docstrings and helps keep their structure predictable across tools and projects.

When documenting your public API with docstrings, keep the following best practices in mind:

• Document public API components with docstrings. Write docstrings for public packages, modules, functions, classes, and methods that others will call or use. This practice provides the first level of documentation for your public API.
• Use docstrings selectively for internal helpers. Internal or private helper functions may not require full docstrings, but adding one can still be valuable when the logic is non-obvious or likely to change.
• Start with a clear one-line summary. Begin the docstring with a short imperative sentence that states what the object does. If the object requires more information, add a blank line and provide additional details. This matches PEP 257 and works well with tools that show just the first line.
• Describe parameters, return values, and errors consistently. Choose a docstring style and adhere to it consistently throughout the project. This way, users and tools will know what to expect. You can choose from reStructuredText, Google, or NumPy docstring styles.
• Focus on purpose and behavior, not implementation details. Explain what the function or object does, what inputs it expects, what it returns, and any important side effects or invariants.
• Keep your docstrings up to date. Revise docstrings when code behavior changes, and avoid duplicating information that can easily fall out of sync. Remember that docstrings are part of your code and documentation.

You can even include basic tests in your docstrings. Python has a standard library module called doctest that can read your docstrings, extract REPL-style examples, and run them as tests. These examples can double as executable documentation when kept simple and focused.

To see how docstrings help, consider a function that adds two numbers together:

🔴 Avoid this:

>>> def add(a, b):
...     """Return the sum of a and b."""
...     return a + b
...

>>> add(100, 200)
300

This function has a docstring, which is good, but it doesn’t provide much guidance beyond the obvious behavior.

✅ Favor this:

type Number = int | float

def add(a: Number, b: Number) -> Number:
    """Return the sum of a and b.

    Args:
        a: The first number.
        b: The second number.

    Returns:
        The sum of the two numbers.
    """
    return a + b

In this version, the one-line summary states the function’s purpose, while the docstring explains how to use it. The type hints communicate expected types to both readers and static analysis tools, reducing the need to repeat that information verbosely in the docstring.

In practice, good function docstrings should answer at least the following questions:

• What does this function do?
• How should the user call it?
• What should the user expect as a result?
• What side effects does it produce, if any?
• When can it fail?

Finally, when building AI-powered applications, clear docstrings can help large language models (LLMs) better understand your code’s intent and available behaviors, especially when combined with well-defined function signatures. This can be useful when building systems such as MCP servers, where tooling metadata and human-readable descriptions work together.

Related Resources

Tutorial

How to Write Docstrings in Python

Learn to write effective Python docstrings that clearly and professionally document your code using best practices and built-in conventions.

basics best-practices

For additional information on related topics, take a look at the following resources:

• Document Your Python Code and Projects With ChatGPT (Tutorial)
• How to Write Docstrings in Python (Quiz)