Python 函数的说明文档（即 **docstring**）**没有强制的“默认格式”**，但存在 **广泛采纳、被主流工具（如 Sphinx、VS Code、PyCharm、Google Colab、`help()`、`pydoc`）原生支持的几种事实标准格式**。其中最主流的是： ✅ **Google 风格（Google Python Style Guide）** ✅ **NumPy/SciPy 风格（NumPy Docstring Standard）** ✅ **reStructuredText 风格（Sphinx 原生格式）** > ⚠️ 注意：Python 语言本身**不解析 docstring 格式** —— `"""..."""` 只是字符串字面量；格式规范由**第三方工具链约定**，用于自动生成 API 文档、IDE 智能提示、类型检查等。 --- ### ✅ 1. Google 风格（最易读、最流行 · 推荐新手首选） ```python def calculate_discounted_price(original_price: float, discount_rate: float = 0.1) -> float: """计算折扣后的价格。 Args: original_price (float): 原价，必须大于 0。 discount_rate (float): 折扣率（0.0 ~ 1.0），默认为 0.1（10%）。 Returns: float: 折扣后价格，保留两位小数。 Raises: ValueError: 当 original_price <= 0 或 discount_rate 超出 [0, 1] 范围时。 Examples: >>> calculate_discounted_price(100.0, 0.2) 80.0 >>> calculate_discounted_price(50.0) 45.0 """ if original_price <= 0: raise ValueError("original_price must be > 0") if not (0.0 <= discount_rate <= 1.0): raise ValueError("discount_rate must be between 0.0 and 1.0") discounted = original_price * (1 - discount_rate) return round(discounted, 2) ``` 🔍 **特点**： - 使用 `Args:`、`Returns:`、`Raises:`、`Examples:` 等清晰标题； - 每个参数占一行，格式为 `name (type): description`； - 支持 `:type name:` 写法（如 `:type discount_rate: float`），但 Google 风格更倾向内联类型； - IDE（如 PyCharm、VS Code）可完美解析并显示悬停提示； - Sphinx + `sphinx.ext.napoleon` 插件可自动转换为 HTML 文档。 --- ### ✅ 2. NumPy/SciPy 风格（科学计算生态标配 · 推荐数据科学项目） ```python def calculate_discounted_price(original_price, discount_rate=0.1): """计算折扣后的价格。 Parameters ---------- original_price : float 原价，必须大于 0。 discount_rate : float, optional 折扣率（0.0 ~ 1.0），默认为 0.1（10%）。 Returns ------- float 折扣后价格，保留两位小数。 Raises ------ ValueError 当 original_price <= 0 或 discount_rate 超出 [0, 1] 范围时。 Examples -------- >>> calculate_discounted_price(100.0, 0.2) 80.0 >>> calculate_discounted_price(50.0) 45.0 """ # ... 函数体同上 ``` 🔍 **特点**： - 参数用 `Parameters` 表格化列出，类型与描述分两行； - `optional` 显式标注默认参数； - `Returns` / `Raises` / `Examples` 同样用分隔线 `------` 对齐； - 被 `numpydoc`、`sphinx.ext.napoleon`、Jupyter Lab 原生支持； - SciPy、pandas、scikit-learn 等库全部采用此风格。 --- ### ✅ 3. reStructuredText（Sphinx 原生格式 · 适合大型文档站） ```python def calculate_discounted_price(original_price, discount_rate=0.1): """计算折扣后的价格。 :param float original_price: 原价，必须大于 0。 :param float discount_rate: 折扣率（0.0 ~ 1.0），默认为 0.1（10%）。 :returns: 折扣后价格，保留两位小数。 :rtype: float :raises ValueError: 当参数非法时。 """ # ... 函数体 ``` 🔍 **特点**： - 使用 `:param type name:`、`:returns:`、`:rtype:` 等指令； - 最轻量，无额外标题块，适合快速编写； - Sphinx 原生解析，无需插件； - 但对 IDE 友好度略低于 Google/NumPy 风格。 --- ### ✅ 4. 纯字符串（最简形式 · 合法但不推荐） ```python def add(a, b): """Return the sum of a and b.""" return a + b ``` ✅ 合法，`help(add)` 和 `?add` 在 IPython 中可显示； ❌ 无法提取参数类型、返回值、异常等结构化信息，工具链无法生成高质量文档。 --- ### 🧩 工具链如何使用 docstring？ | 工具 | 如何利用 docstring | |------|-------------------| | `help(func)` / `?func`（IPython/Jupyter） | 直接打印字符串，**不解析格式**，但会识别 `Args:` 等关键词做粗略高亮 | | VS Code / PyCharm | 自动解析 Google/NumPy 风格，显示悬停提示（含参数名、类型、描述） | | Sphinx + `napoleon` | 将 Google/NumPy 风格转为 HTML/API 文档（支持交叉引用、类型链接） | | `pydoc func` | 命令行查看，基础格式支持良好 | | `mypy` / `pyright` | **不解析 docstring 类型**，需配合类型注解（`-> float`, `: float`）做静态检查 | > ✅ **最佳实践 = 类型注解 + Google/NumPy docstring** > ```python > def func(x: int, y: str) -> list[str]: > """Description... > > Args: > x: ... > y: ... > > Returns: > ... > """ > ``` --- ### 📜 PEP 257：官方 docstring 指南（非格式，而是原则） Python 官方 PEP 257 规定了 docstring 的**通用原则**（非具体语法）： - 必须用 `"""triple double quotes"""`（不能用单引号或双引号）； - 模块、类、函数、方法**必须有 docstring**（`__init__` 除外，其类 docstring 已涵盖）； - 首行是**简洁摘要**（句号结尾），空一行后写详细描述； - 不要写 “This function does...”，直接描述行为； - 使用现在时、祈使语气（"Compute", "Return", "Raise"）。 ---