Docstring Style Guide

All AMMM code uses Google-style docstrings.

Function/Method Format

Type1 = Type2 = ReturnType = object

def function_name(param1: Type1, param2: Type2) -> ReturnType:
    """Brief one-line summary.

    Longer description if needed. Can span multiple lines. Explain what the
    function does, any important algorithms, or business logic.

    Args:
        param1: Description of param1. Type is in the signature.
        param2: Description of param2. Can span multiple lines if needed.

    Returns:
        Description of return value. Type is in the signature.

    Raises:
        ValueError: When and why this is raised.
        TypeError: When and why this is raised.

    Example:
        >>> result = function_name(value1, value2)
        >>> print(result)
        Expected output

    Note:
        Any important notes or warnings.
    """

Class Docstrings

class ClassName:
    """Brief one-line class summary.

    Longer class description explaining purpose, usage, and important patterns.

    Attributes:
        attr1: Description of attribute.
        attr2: Description of attribute.

    Example:
        >>> obj = ClassName(param)
        >>> obj.method()
        Expected behaviour
    """

Common Sections

• Args: Function/method parameters
• Returns: What the function returns
• Raises: Exceptions that may be raised
• Yields: For generator functions
• Example: Usage examples (encouraged!)
• Note: Important notes
• Warning: Important warnings
• See Also: Related functions/classes

Conversion Examples

Before (NumPy-style)

def calculate_roi(spend, revenue):
    """
    Calculate return on investment.

    Parameters
    ----------
    spend : float
        The amount spent on advertising.
    revenue : float
        The revenue generated.

    Returns
    -------
    float
        The ROI ratio.
    """

After (Google-style)

def calculate_roi(spend: float, revenue: float) -> float:
    """Calculates return on investment.

    Args:
        spend: The amount spent on advertising.
        revenue: The revenue generated.

    Returns:
        The ROI ratio (revenue/spend).

    Example:
        >>> roi = calculate_roi(1000, 1500)
        >>> print(f"ROI: {roi:.2f}")
        ROI: 1.50
    """