What are the most common Python docstring formats?

 

Python docstrings are used to document code, providing information about the purpose, usage, and details of functions, classes, methods, and modules. While there isn't a single "official" format for docstrings, there are several common conventions and formats that developers often use. Here are three of the most common docstring formats with examples:

1. Google Style Docstrings:

   Google-style docstrings follow the format used by the Sphinx documentation generator and are quite popular in the Python community. They use triple double-quotes (""") for multi-line docstrings and include sections for a brief description, parameters, returns, and examples.

   python

def add(a, b):
    """
    Calculate the sum of two numbers.

    Args:
        a (int): The first number.
        b (int): The second number.

    Returns:
        int: The sum of a and b.

    Examples:
        >>> add(2, 3)
        5
    """
    return a + b

Numpy/Scipy Style Docstrings:

Numpy-style docstrings are commonly used in scientific computing and data analysis libraries. They are similar to Google-style docstrings but follow a specific format that includes sections like "Parameters," "Returns," and "Notes."

python

def subtract(a, b):
    """
    Calculate the difference between two numbers.

    Parameters:
        a (int): The first number.
        b (int): The second number.

    Returns:
        int: The difference between a and b.

    Notes:
        This function performs subtraction.
    """
    return a - b

reStructuredText (reST) Style Docstrings:

reStructuredText-style docstrings are used in projects that follow the Python Enhancement Proposal (PEP) 287. They use reST markup and provide structured information in a way that's suitable for generating documentation with tools like Sphinx.

python

3. def multiply(a, b):
       """
       Calculate the product of two numbers.
   
       :param a: The first number.
       :type a: int
       :param b: The second number.
       :type b: int
       :return: The product of a and b.
       :rtype: int
   
       .. note:: This function performs multiplication.
       """
       return a * b
   

These are just three of the most common docstring formats in Python, and there are other variations and custom formats used by different projects. The key is to choose a format that fits your project's needs and maintain consistency within your codebase. Properly documented code makes it easier for developers (including yourself) to understand and use your code, and it can also be helpful when generating documentation using tools like Sphinx.