Introduction

Python does not enforce one official docstring syntax, but a few formats dominate real projects. The most common choices are plain PEP 257 style, Google style, NumPy style, and reStructuredText-style field lists, usually chosen based on team preference and documentation tooling.

The Baseline: PEP 257

PEP 257 is not a full parameter annotation format. It is the general convention for how Python docstrings should be written: a short summary line, optional blank line, and a longer description if needed.

Example:

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

Every other popular style sits on top of that idea. So when people say “PEP-compliant docstrings,” they usually mean the shape and tone come from PEP 257 even if parameters are documented using another format.

Google Style

Google style is popular because it is easy to read in source code. It uses labeled sections such as Args, Returns, and Raises.

1def divide(a: float, b: float) -> float:
2    """Divide one number by another.
3
4    Args:
5        a: Dividend.
6        b: Divisor.
7
8    Returns:
9        The quotient.
10
11    Raises:
12        ZeroDivisionError: If `b` is zero.
13    """
14    return a / b

This format is common in application code because it is compact and approachable.

NumPy Style

NumPy style is especially common in scientific and data-focused Python projects. It uses underlined section headers and tends to be verbose in a structured way.

1def normalize(values):
2    """Scale numeric values to sum to one.
3
4    Parameters
5    ----------
6    values : list[float]
7        Input numbers.
8
9    Returns
10    -------
11    list[float]
12        Normalized numbers whose sum is one.
13    """
14    total = sum(values)
15    return [value / total for value in values]

This style works well when documenting arrays, shapes, mathematical assumptions, and detailed return semantics.

reStructuredText Style

reStructuredText-style docstrings are often used with Sphinx and field-based documentation.

1def greet(name: str) -> str:
2    """Build a greeting message.
3
4    :param name: The user name.
5    :type name: str
6    :return: A greeting string.
7    :rtype: str
8    """
9    return f"Hello, {name}!"

This style is still common in projects that generate documentation directly with Sphinx and want explicit field markup in the source.

Which Format Is Most Common

In everyday Python repositories, Google and NumPy are probably the most recognizable structured formats. reStructuredText is still widely used, especially in older Sphinx-heavy projects, but many teams prefer Google or NumPy because they are easier to write and read in raw source files.

The real rule is consistency. A project with one clear docstring style is far easier to maintain than a project that mixes three of them.

Choosing a Format

A practical way to choose is:

• use Google style for general application and backend code
• use NumPy style for scientific, data, or research-heavy libraries
• use reStructuredText if your documentation tooling or team conventions already depend on it
• keep even simple one-line docstrings aligned with PEP 257 principles

The tooling should also influence the decision. Sphinx with Napoleon handles Google and NumPy well, so you do not need to choose reStructuredText just to generate docs.

Common Pitfalls

The biggest mistake is mixing styles across the same project. That makes the codebase feel inconsistent and harder to search.

Another mistake is writing docstrings that restate the function name instead of explaining behavior, inputs, side effects, or constraints.

A third mistake is documenting types in the docstring and in annotations inconsistently. If you already use type hints, keep the docstring focused on meaning rather than duplicating obvious syntax.

Summary

• Plain PEP 257 conventions define the general shape of Python docstrings.
• The most common structured formats are Google, NumPy, and reStructuredText.
• Google style is popular for general software projects.
• NumPy style is common in scientific and data-oriented code.
• Pick one format per project and apply it consistently.