Course contentsShow
← Python
Lesson 199 of 1,0603. Functions and ModularizationFree lesson

Documenting Parameters and Return Values with Google Style

Learners will adopt the Google docstring format to provide detailed technical specifications for function arguments, return values, and raised exceptions.

In this lesson, you will learn how to write clear, professional documentation for your functions using the industry-standard Google Python Style Guide.

While PEP 257 teaches us the basic structure of a docstring, the Google Style takes it a step further by providing a structured template for describing your function’s inputs, outputs, and errors. This makes your code readable for others and allows IDEs to provide helpful tooltips.

The Anatomy of a Google-Style Docstring

A Google-style docstring uses specific sections: Args:, Returns:, and Raises:. Each parameter is listed by name, followed by a colon and its description.

Consider this example of a function that divides two numbers:

def divide_numbers(numerator: float, denominator: float) -> float:
    """Divides two numbers and returns the result.

    Args:
        numerator: The number to be divided.
        denominator: The number to divide by.

    Returns:
        The quotient of the two numbers.

    Raises:
        ZeroDivisionError: If denominator is zero.
    """
    if denominator == 0:
        raise ZeroDivisionError("Cannot divide by zero.")
    return numerator / denominator

Why Use This Format?

  1. Readability: By separating the "what it does" from the "how it works," a developer can scan the Args and Returns sections without reading the entire implementation.
  2. Explicit Expectations: Explicitly documenting the Raises section warns users about potential side effects or crashes, allowing them to write more robust code by anticipating exceptions.
  3. Tool Integration: Modern documentation generators (like Sphinx) and code editors parse this structure automatically, turning your docstrings into searchable, formatted technical manuals.

When writing your own functions, remember to keep your descriptions concise. If a parameter is complex, you can extend the description to a new line, indented by four spaces under the parameter name. By adopting this standard, you move from writing code that simply "works" to writing code that is professional, maintainable, and easy for your team to understand at a glance.

Key Takeaway: The Google Style docstring uses structured Args:, Returns:, and Raises: sections to transform your function comments into comprehensive technical specifications.