在 Python 中，docstrings 是一种用于记录模块、类、函数和方法的方法。它们写在三引号（""" """ 或 ''' '''）之间，并可以跨越多行。
Docstrings 作为一种方便的方式，将文档与 Python 代码关联起来。它们可以通过相应 Python 对象的 __doc__ 属性进行访问。下面是在 Python 中编写 docstrings 的不同方式：
单行 Docstrings
单行 docstrings 用于简短且简单的文档记录。它们提供了一个函数或方法作用的简明描述。单行 docstrings 应该在三引号内写在一行为宜，并以句点结束。
示例
在下面的例子中，我们使用单行 docstring 来写一段文本：
def add(a, b):
"""Return the sum of two numbers."""
return a + b
result = add(5, 3)
print("Sum:", result)
多行 Docstrings
多行 docstrings 用于更详细的文档记录。它们提供了更全面的描述，包括参数、返回值和其他相关信息。多行 docstrings 开始和结束于三引号，并包含一个摘要行接着是一个空行以及更详细的描述。
示例
下面的例子使用了多行 docstrings 作为代码的解释：
def multiply(a, b):
"""
Multiply two numbers and return the result.
Parameters:
a (int or float): The first number.
b (int or float): The second number.
Returns:
int or float: The result of multiplying a and b.
"""
return a * b
result = multiply(5, 3)
print("Product:", result)
模块的 Docstrings
当为模块编写 docstrings 时，将 docstring 放在模块顶部，在任何导入语句之后。模块 docstring 提供了模块功能的概览，并列出了模块提供的主要组件，如函数、类和异常。
示例
在这个例子中，我们展示了在 Python 中使用模块 docstrings：
import os
"""
This module provides Utility functions for file handling operations.
Functions:
- 'read_file(filepath)': Reads and returns the contents of the file.
- 'write_file(filepath, content)': Writes content to the specified file.
Classes:
- 'FileNotFoundError': Raised when a file is not found.
Example usage:
>>> import file_utils
>>> content = file_utils.read_file("example.txt")
>>> print(content)
'Hello, world!'
>>> file_utils.write_file("output.txt", "This is a test.")
"""
print("This is os module")
类的 Docstrings
类可以拥有 docstrings 来描述它们的目的和用途。类内的每个方法也可以有自己的 docstring。类 docstring 应该提供类及其方法的概览。
示例
在下面的例子中，我们展示了 Python 中类 docstrings 的使用：
class Calculator:
"""
A simple calculator class to perform basic arithmetic operations.
Methods:
- add(a, b): Return the sum of two numbers.
- multiply(a, b): Return the product of two numbers.
"""
def add(self, a, b):
"""Return the sum of two numbers."""
return a + b
def multiply(self, a, b):
"""
Multiply two numbers and return the result.
Parameters:
a (int or float): The first number.
b (int or float): The second number.
Returns:
int or float: The result of multiplying a and b.
"""
return a * b
cal = Calculator()
print(cal.add(87, 98))
print(cal.multiply(87, 98))
访问 Docstrings
Python 中的 docstrings 可以通过它们所记录的对象的 __doc__ 属性来访问。这个属性包含了与对象相关联的文档字符串（docstring），提供了一种访问和展示有关函数、类、模块或方法的目的和用途的信息的方式。
示例
在下面的例子中，我们定义了两个函数，“add” 和 “multiply”，每个函数都有一个描述其参数和返回值的 docstring。然后我们使用 __doc__ 属性来访问并打印这些 docstrings：
def add(a, b):
"""
Adds two numbers together.
Parameters:
a (int): The first number.
b (int): The second number.
Returns:
int: The sum of a and b.
"""
return a + b
result = add(5, 3)
print("Sum:", result)
def multiply(x, y):
"""
Multiplies two numbers together.
Parameters:
x (int): The first number.
y (int): The second number.
Returns:
int: The product of x and y.
"""
return x * y
result = multiply(4, 7)
print("Product:", result)
print(add.__doc__)
print(multiply.__doc__)
编写 Docstrings 的最佳实践
以下是编写 Python docstrings 的最佳实践：
-
清晰简洁：确保 docstring 清晰解释代码的目的和用途，避免不必要的细节。
-
正确语法和拼写：确保 docstring 书写良好，语法和拼写正确。
-
遵循约定：使用标准格式化 docstrings 的约定，如 Google 样式、NumPy 样式或 Sphinx 样式。
-
包含示例：在适用的地方提供示例来说明如何使用所记录的代码。
Google 样式 Docstring
Google 样式 docstrings 提供了一种结构化的方式来记录 Python 代码，使用缩进和标题。它们旨在易于阅读和信息丰富，遵循特定的格式。
示例
下面是一个带有 Google 样式 docstring 的函数示例：
def divide(dividend, divisor):
"""
Divide two numbers and return the result.
Args:
dividend (float): The number to be divided.
divisor (float): The number to divide by.
Returns:
float: The result of the division.
Raises:
ValueError: If `divisor` is zero.
"""
if divisor == 0:
raise ValueError("Cannot divide by zero")
return dividend / divisor
result = divide(4, 7)
print("Division:", result)
NumPy/SciPy 样式 Docstring
NumPy/SciPy 样式的 docstrings 在科学计算中很常见。它们包括参数、返回值和示例的部分。
示例
下面是一个带有 NumPy/SciPy 样式 docstring 的函数示例：
def fibonacci(n):
"""
Compute the nth Fibonacci number.
Parameters
----------
n : int
The index of the Fibonacci number to compute.
Returns
-------
int
The nth Fibonacci number.
Examples
--------
>>> fibonacci(0)
0
>>> fibonacci(5)
5
>>> fibonacci(10)
55
"""
if n == 0:
return 0
elif n == 1:
return 1
else:
return fibonacci(n-1) + fibonacci(n-2)
result = fibonacci(4)
print("Result:", result)
Sphinx 样式 Docstring
Sphinx 样式 docstrings 与 Sphinx 文档生成器兼容，并使用 reStructuredText 格式。
reStructuredText（reST）是一种轻量级标记语言，用于创建结构化的文本文档。Sphinx 文档生成器接受“reStructuredText”文件作为输入，并生成各种格式的高质量文档，包括 HTML、PDF、ePub 等。
示例
下面是一个带有 Sphinx 样式 docstring 的函数示例：
def divide(dividend, divisor):
"""
Divide two numbers and return the result.
Args:
dividend (float): The number to be divided.
divisor (float): The number to divide by.
Returns:
float: The result of the division.
Raises:
ValueError: If `divisor` is zero.
"""
if divisor == 0:
raise ValueError("Cannot divide by zero")
return dividend / divisor
result = divide(76, 37)
print("Result:", result)
Docstring 与注释的区别
下面列出了 Python docstrings 与注释之间的区别，重点在于它们的目的、格式、用途和可访问性：
| Docstring |
注释 |
| 用于记录 Python 对象，如函数、类、方法、模块或包。 |
用于注释代码给人阅读，提供上下文，或暂时禁用代码。 |
写在三引号（""" """ 或 ''' '''）内，并紧接对象定义之后。 |
以 # 符号开头，并放在被注释代码的同一行。 |
| 作为对象的属性存储并可以程序化访问。 |
在执行期间被 Python 解释器忽略，纯粹为人理解。 |
使用对象的 __doc__ 属性访问。 |
不可程序化访问；仅存在于源代码中。 |