一句话概括
Docstrings（文档字符串）是 Python 代码中的一种字符串字面量，用于解释模块、类、函数或方法的作用、参数、返回值等，它不是普通的注释，而是 Python 语言的一部分，可以被解释器和各种工具识别和提取。
Docstrings 的核心作用
可以把 Docstrings 理解为是给你的代码写的“用户手册”或“API 文档”，它的主要作用可以归纳为以下几点：
代码文档化
这是最核心、最直接的作用，Docstrings 提供了一种标准的方式来记录代码的功能、目的、用法和实现细节，使得代码更易于理解、维护和协作。
- 对开发者友好：当你或他人几个月后回来看这段代码时，一个好的 Docstring 能立刻让你明白这段代码是做什么的，应该怎么用。
- 对使用者友好：如果你在写一个库或框架，其他开发者会通过你的 Docstring 来学习如何使用你的 API。
提供交互式帮助
Python 的内置函数 help() 和 在 IPython/Jupyter Notebook 中可以直接读取并显示 Docstring，这是 Python 交互式编程的一大特色。
示例：
def add(a, b):
"""将两个数字相加并返回结果。
Args:
a (int or float): 第一个加数。
b (int or float): 第二个加数。
Returns:
int or float: a 和 b 的和。
"""
return a + b
# 在 Python 交互式环境中或 Jupyter Notebook 中运行：
# help(add)
# 或者直接输入: add?
运行 help(add) 后，你会看到格式清晰的输出：
Help on function add in module __main__:
add(a, b)
将两个数字相加并返回结果。
Args:
a (int or float): 第一个加数。
b (int or float): 第二个加数。
Returns:
int or float: a 和 b 的和。自动化文档生成
Docstrings 是 Sphinx、MkDocs、pdoc 等自动化文档生成工具的核心数据源，你只需要在代码中写好 Docstring，这些工具就能扫描你的代码，自动生成美观、专业的 HTML 或 PDF 文档网站，而无需你手动编写维护一份单独的文档。
代码规范与最佳实践
遵循 PEP 257（Python Docstring Conventions）规范编写 Docstring，是 Python 社区的公认最佳实践，它强制开发者思考函数/类的接口和边界情况，从而写出更健壮、设计更好的代码。
Docstrings 与普通注释的区别
这是一个非常重要的概念,初学者很容易混淆。
| 特性 | Docstrings | 普通注释 |
|---|---|---|
| 定义 | 包裹在三重双引号 或三重单引号 中的字符串。 | 以 开头，直到行尾的文本。 |
| 语法 | 是 Python 语法的一部分，是一个真正的字符串对象。 | 不是语法的一部分，仅对人类可读，解释器会忽略。 |
| 访问方式 | 可以通过 __doc__ 属性访问，可以被 help() 等工具提取。 |
无法通过程序直接访问，仅存在于源代码中。 |
| 作用 | 描述“做什么”（What）和“为什么”（Why），解释接口、用途。 | 描述“怎么做”（How），解释具体的实现逻辑、临时提醒等。 |
| 位置 | 必须是模块、类、函数或方法中的第一个语句。 | 可以出现在代码的任何位置。 |
简单比喻：
- Docstring 是一本书的封面介绍和章节摘要，告诉读者这本书讲了什么，如何阅读。
- 普通注释 是书页里的脚注和批注，解释某个具体段落的含义或作者的临时想法。
如何编写一个好的 Docstring？（遵循 PEP 257）
一个好的 Docstring 通常包含以下几个部分，使用多行字符串格式：
def function_name(arg1, arg2):
"""这是函数的简短描述（一行）。
这是函数的详细描述，它可以跨越多行，解释函数的更广泛背景、
使用场景或需要注意的边界情况。
Args:
arg1 (int): 第一个参数的描述，说明它是什么，以及它的类型。
arg2 (str, optional): 第二个参数的描述，如果参数有默认值，需要在这里说明。
默认值为 'default_value'。
Returns:
bool: 返回值的描述，说明返回的是什么，以及它的类型。
Raises:
ValueError: 当 arg1 小于 0 时会抛出此异常。
TypeError: 当 arg2 不是字符串类型时抛出此异常。
Examples:
>>> function_name(10, 'hello')
True
"""
# 函数实现...
pass
常见的 Docstring 风格：结构类似，但格式上有几种主流风格：
- Google 风格：非常直观，广泛使用。
- reStructuredText (reST / Sphinx) 风格：功能强大，是 Sphinx 的默认风格。
- NumPy/SciPy 风格：更详细，特别适合复杂的科学计算函数。
现代工具（如 VS Code 的 Python 插件）通常能很好地兼容这几种风格。
代码示例
模块级 Docstring
"""这个模块提供了一些基本的数学工具函数。 这个模块主要用于演示如何在模块级别使用 Docstring。 它包含两个简单的函数。 """ # ... 模块代码 ...
类级 Docstring
class Calculator:
"""一个简单的计算器类。
这个类提供了基本的加、减、乘、除运算。
所有方法都返回一个浮点数结果。
"""
def add(self, a, b):
"""将两个数相加。"""
return a + b
# ... 其他方法 ...
函数/方法级 Docstring
def calculate_average(numbers):
"""计算一个数字列表的平均值。
Args:
numbers (list of int or float): 一个包含数字的列表。
Returns:
float: 列表中数字的平均值，如果列表为空，则返回 0。
Examples:
>>> calculate_average([1, 2, 3, 4])
2.5
>>> calculate_average([])
0
"""
if not numbers:
return 0
return sum(numbers) / len(numbers)
Docstrings 是 Python 开发中不可或缺的一部分，它不仅仅是为了满足代码规范，更是一种提升代码质量、促进团队协作、降低维护成本的有效投资，养成编写 Docstrings 的习惯，会让你成为一个更专业、更受尊敬的 Python 开发者。
