Python 中如何编写文档字符串 (docstring)？

推荐答案

在 Python 中，文档字符串（docstring）是用于描述模块、类、函数或方法的字符串。它通常位于定义的开始部分，并用三重引号（""" 或 '''）括起来。以下是一个示例：

-- -------------------- ---- -------
--- ------ ---
    ---
    --- --- ------- --- ------ --- -------

    -----------
    - ---- -- ------- --- ----- -------
    - ---- -- ------- --- ------ -------

    --------
    --- -- ------ --- --- -- - --- --
    ---
    ------ - - -

在这个示例中，add 函数的文档字符串描述了函数的功能、参数和返回值。

本题详细解读

1. 文档字符串的位置

文档字符串通常位于模块、类、函数或方法的定义之后，但在代码块之前。例如：

def my_function():
    """This is a docstring."""
    pass

2. 文档字符串的格式

文档字符串通常使用三重引号（""" 或 '''）括起来，并且可以跨越多行。常见的格式包括：

• 单行文档字符串：适用于简单的描述。

  def my_function():
      """This is a single-line docstring."""
      pass

• 多行文档字符串：适用于更详细的描述，通常包括函数的功能、参数、返回值等信息。

  def my_function():
      """
      This is a multi-line docstring.
  
      It can span multiple lines and provide detailed information
      about the function, its parameters, and its return value.
      """
      pass

3. 文档字符串的内容

文档字符串的内容通常包括以下部分：

• 功能描述：简要描述函数或方法的功能。
• 参数说明：列出函数或方法的参数及其类型和含义。
• 返回值说明：描述函数或方法的返回值及其类型。
• 示例：提供使用函数或方法的示例代码。

4. 访问文档字符串

可以通过 __doc__ 属性访问文档字符串。例如：

print(my_function.__doc__)

这将输出 my_function 的文档字符串。

5. 文档字符串的工具支持

文档字符串可以被一些工具（如 Sphinx、pydoc 等）自动提取并生成文档。因此，编写良好的文档字符串有助于生成高质量的文档。

6. 最佳实践

• 保持文档字符串简洁明了。
• 使用一致的格式和风格。
• 及时更新文档字符串以反映代码的变化。

通过遵循这些最佳实践，你可以编写出清晰、有用的文档字符串，从而提高代码的可读性和可维护性。