Python Docstrings

Python docstrings

Created By: chatGPT

In Python, docstrings are important for documenting modules, functions, classes, or methods. A docstring allows developers to understand what a function does without delving into the implementation. Docstrings are written in a triple quoted string format and can include descriptions of parameters, return values, exceptions, and more.

def add(a, b):
    """
    Add two numbers.

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

    Returns:
    int or float: The sum of a and b.
    """
    return a + b

PEP 257 is the conventions guide for Python docstrings. According to this, the first line of a docstring should be a short summary of the function's purpose. If additional information is needed, it can be provided in subsequent lines. Below is an example illustrating a docstring for a class.

class Calculator:
    """
    A simple calculator class for basic operations.

    Methods:
        add(a, b)
            Returns the sum of a and b.
        subtract(a, b)
            Returns the difference of a and b.
    """

    def add(self, a, b):
        return a + b

    def subtract(self, a, b):
        return a - b

When writing docstrings, ensure they are clear and concise. Include examples if necessary, demonstrating how to use the function or method. Here’s an example with an added usage description.

def multiply(a, b):
    """
    Multiply two numbers together and return the product.

    Example:
    >>> result = multiply(2, 3)
    >>> print(result)
    6
    """
    return a * b

You can access docstrings programmatically using the __doc__ attribute of functions, classes, and modules. This is particularly useful for debugging or generating documentation dynamically.

print(add.__doc__)
print(Calculator.__doc__)