Python Docstring

Python docstring 是 Python 中的一种文档注释格式。它可以帮助程序员更好地理解代码的作用和实现。在 Python 中，每个模块，类，方法和函数都应该至少有一个 docstring。

格式

Python docstring 的格式非常简单，它位于模块，类，方法或函数的顶部。

在模块或类的情况下，docstring 应该出现在 import 语句之后，在 class 语句之前。在函数或方法的情况下，docstring 应该出现在 def 语句之后，在函数或方法的行之前。

docstring 以三个双引号或三个单引号开始和结束，格式如下：

"""
This is a docstring.
"""

或

'''
This is a docstring.
'''

docstring 可以包含多行文本和其他内容，例如函数参数，返回值和示例代码。

示例

以下是一个函数的例子，其中包含了一个简单的 docstring：

def add_numbers(a, b):
    """Return the sum of two numbers."""
    return a + b

这个 docstring 说明了函数做了什么，并且在函数被调用时可以为函数提供上下文。

docstring 可以使用 reStructuredText 等标记语言格式化。下面是一个更复杂的示例，其中包含函数的参数，返回值和示例代码：

def divide_numbers(numerator, denominator):
    """
    Divide two numbers and return the result.

    :param numerator: The number to be divided.
    :type numerator: int or float
    :param denominator: The number to divide by.
    :type denominator: int or float
    :return: The result of the division.
    :rtype: float
    :raises ZeroDivisionError: If the denominator is zero.
    
    Examples:
    >>> divide_numbers(4, 2)
    2.0
    >>> divide_numbers(4, 0)
    Traceback (most recent call last):
        ...
    ZeroDivisionError: division by zero
    """
    if denominator == 0:
        raise ZeroDivisionError("The denominator cannot be zero.")
    return numerator / denominator

我们可以看到，docstring 的格式使代码更容易阅读和理解，特别是在团队开发中。