Python code documentation

Last reviewed

February 27, 2025

Last modified

March 25, 2025

Further reading

Documenting Python code

Code comments

Code comments are inline annotations meant for developers who read or maintain the source code. They should:

  • explain parts that are not intuitive from the code itself
  • explain the purpose of a piece of code (why over how)
  • need to be kept up-to-date as wrong comments are not caught through testing
  • do not replace readable and structured code
  • do not turn old code into commented zombie code (see code smells)
  • do not repeat in natural language what is written in your code, e.g.
# Now we check if the age of a patient is greater than 18
if age_patient > 18:

Docstrings

Docstrings are structured comments, associated with segments (rather than lines) of code which can be used to generate documentation for users (and yourself!) of your project. They allow you to provide documentation to a segment (function, class, method) that is relevant for the user. Docstrings are placed in triple quotes """ and enable automated generation of API documentation.

Two docstring styles are commonly used for their readability:

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    """
    return True

⮕ Check out the NumPy style guide or a full example.

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Args:
        arg1 (int): Description of arg1
        arg2 (str): Description of arg2

    Returns:
        bool: Description of return value

    """
    return True

⮕ Check out the Google style guide or a full example.

Docstring formatting

Python’s PEP 257 provides guidelines on how to effectively write docstrings to ensure they are clear, concise, and useful. Some pointers:

  • The summary sentence of the docstring should appear on the same line as the opening triple quotes.
  • The closing triple quotes should be placed on a separate line, except for one-line docstrings.
  • Docstrings for methods and functions should not have blank lines before or after them.
def find_max(numbers):
    """Find the maximum value in a list of numbers.

    Parameters
    ----------
    numbers : iterable
        A collection of numerical values from which the maximum will be determined.

    Returns
    -------
    max_value : `float`
        The highest number in the given list of numbers.
    """
    pass
  • Docstrings for classes should immediately follow the class definition without any preceding blank lines. However, a single blank line should follow the docstring, separating it from subsequent code such as class variables or the init method.
class Circle(object):
    """A circle defined by its radius.

    Parameters
    ----------
    radius : `float`
        The radius of the circle.
    """

    def __init__(self, radius):
        self.radius = radius
  • The content of a docstring must align with the indentation level of the code it documents.
def get_length(items):
    """Calculate the number of items in the list.

    Parameters
    ----------
    items : list
        A list whose length is to be determined.

    Returns
    -------
    length : int
        The number of items in the list.
    """
    return len(items)
def get_length(items):
    """Calculate the number of items in the list.

Parameters
----------
items : list
    A list whose length is to be determined.

Returns
-------
length : int
    The number of items in the list.
"""
    return len(items)
Learn more

Docstring contents

Formatting conventions are important for clarity and readability across different APIs or libraries. Here we adhere to the numpydoc convention.

Summaries

Docstrings should start with a one-sentence summary and if additional clarification is needed, you could add an extended summary. For functions and methods, use imperative voice, framing its summary as a command or instruction that the user can execute through the API. For classes, the summary should clearly describe what the class represents or its primary responsibility.

Parameters and arguments

The Parameters section lists the input parameters of a class, function, or method. It should include the parameter name, type, and a brief description of what the parameter represents. Parameters are listed in the same order as they appear in the function definition.

Describing parameters

Basic example:

def calcDistance(x, y, x0=0., y0=0., **kwargs):
    """Calculate the distance between two points.

    Parameters
    ----------
    x : `float`
        X-axis coordinate.
    y : `float`
        Y-axis coordinate.
    x0 : `float`, optional
        X-axis coordinate for the second point (the origin,
        by default).

        Descriptions can have multiple paragraphs, and lists:

        - First list item.
        - Second list item.
    y0 : `float`, optional
        Y-axis coordinate for the second point (the origin,
        by default).
    **kwargs
        Additional keyword arguments passed to
        `calcExternalApi`.
    """

Returns and Yields

Returns is an explanation about the returned values and their types, following the same format as Parameters. This is applicable to functions and methods. Use Yields for generators.

def getCoord(self):
    """Get the point's pixel coordinate.

    Returns
    -------
    x : `int`
        X-axis pixel coordinate.
    y : `int`
        Y-axis pixel coordinate.
    """
    return self._x, self._y
def items(self):
    """Iterate over items in the container.

    Yields
    ------
    key : `str`
        An item's key.
    value : obj
        An item's value.
    """
    for key, value in self._data.items():
        yield key, value

Raises

For classes, methods, and functions the Raises section is used to describe exceptions that are explicitly raised.

Raises
------
IOError
    Raised if the input file cannot be read.
TypeError
    Raised if parameter ``example`` is an invalid type.
Learn more