用AI写Python文档字符串：从平庸到精准的提示词实战

维护一个塞满工具函数的 Python 仓库是种什么体验？小而常用的代码片段，几个月里随手写就，几乎没有文档。等到某天你盯着 process_complex_csv_data(filepath, schema_config, output_dir) 发呆，想不起它到底做了什么，就只能一头扎进函数内部重新读一遍。于是很自然地，念头转向了大语言模型——让 AI 帮忙批量生成 docstring，省下几个小时的苦力活，听起来太美好了。

但实践下来，这件事远没有想象中简单。一位开发者分享了他与 AI 搏斗、从生成一堆"正确但无用"的文档，到最终找到有效提示策略的完整过程。核心结论很直接：AI 不是魔法文档生成器，它的产出质量，完全取决于你喂给它的指令和上下文。

直接丢代码的尝试，为什么失败了

最初的做法很符合直觉：抓一个函数，粘贴到 OpenAI playground 或直接调用 gpt-3.5-turbo，配上一句简单提示——"为下面这个 Python 函数生成 Google 风格的 docstring"。

以这个字符串归一化函数为例：

import re

def normalize_string_for_search(text: str, lower_case: bool = True, strip_punct: bool = True) -> str:
    if lower_case:
        text = text.lower()
    if strip_punct:
        text = re.sub(r'[^\w\s]', '', text)
    return text

gpt-3.5-turbo 给出的典型结果是这样的：

"""
Normalizes a string for search purposes.

Args:
    text (str): The input string to normalize.
    lower_case (bool, optional): Whether to convert the string to lowercase. Defaults to True.
    strip_punct (bool, optional): Whether to strip punctuation from the string. Defaults to True.

Returns:
    str: The normalized string.
"""

问题在哪？它不算错，但也几乎没用。"Normalizes a string for search purposes" 不过是把函数名换了个说法重复一遍。它没告诉你究竟是怎么归一化的——strip 的是哪类标点？传入 "Hello, World!" 用默认参数会得到什么？没有使用示例，没有边界情况说明，纯属废话。作者形容这是文档版的"this function processes data"——谢谢你，队长，显而易见。

更糟的是投入产出比。作者前后花了整整四个小时，尝试了各种变体："更具体一点！""加上例子！""像人一样思考！"结果从略好到同样平庸不等。甚至换成 gpt-4 配同样的简单提示，虽然聪明了一点，依然难以推断函数的意图和影响，只能停留在代码表层。他的生产力一度变成负数——生成的 docstring 需要的人工审查和修正，比从头手写还费劲。

Google 风格 docstring 是 Python 社区广泛采用的文档规范之一，由 Google 在其 Python 代码风格指南中推广。它的结构包含一行简短描述、可选的详细说明段落，以及用缩进分节的 Args:、Returns:、Raises: 和 Examples: 等标签块。与 NumPy 风格（用横线分隔各节）和 reStructuredText 风格（用 :param: 前缀）相比，Google 风格可读性较强，视觉层次清晰，因此被 Sphinx 等文档生成工具和大量开源项目广泛支持。理解这一规范的具体要求，有助于判断 AI 生成的 docstring 究竟差在哪里——不只是内容空洞，有时还会在格式层面违反规范，导致文档工具解析失败。

真正起作用的做法：给 AI 看"单元测试"

转折点出现在作者意识到，自己一直把 AI 当成能自行推断上下文的魔法黑盒。但它做不到，至少做不全。你得明确告诉它要找什么、这段文档服务于什么目的。关键是——它需要示例，而不只是指令。

有效的策略是给 AI 更丰富的上下文，把它当成一个需要理解"为什么"和"怎么做"而非仅仅"做什么"的初级开发者。作者使用 gpt-4-0125-preview 模型，提示词结构大致如下：

你是一名资深 Python 开发者，负责编写完整的 Google 风格 docstring。
文档需说明函数功能、参数、返回值，并包含至少两个清晰、不同的使用示例，
如适用则覆盖边界情况。

这是 Python 函数：

[函数代码]

预期行为示例：
1. 输入 text="Hello, World!", lower_case=True, strip_punct=True -> 输出 "hello world"
2. 输入 text="AI & ML rocks!", lower_case=False, strip_punct=True -> 输出 "AI ML rocks"
3. 输入 text="What's up, Doc?", lower_case=True, strip_punct=False -> 输出 "what's up, doc?"

现在为上面的函数生成完整的 Google 风格 docstring，并融入这些示例。

效果立竿见影。通过给出具体的输入与预期输出，作者实际上是在用模型能真正理解的方式教它函数的行为——这就像是给文档写单元测试。生成质量从"大约 30% 可用"跃升到"约 85% 可用"。

改进后的 docstring 变成了这样：

"""
Normalizes a string for search queries by optionally converting it to lowercase and stripping punctuation.

Args:
    text (str): The input string to be normalized.
    lower_case (bool, optional): If True, converts the string to lowercase. Defaults to True.
    strip_punct (bool, optional): If True, removes all punctuation characters (non-alphanumeric, non-whitespace). Defaults to True.

Returns:
    str: The normalized string suitable for search.

Examples:
    >>> normalize_string_for_search("Hello, World!", lower_case=True, strip_punct=True)
    'hello world'
    >>> normalize_string_for_search("AI & ML rocks!", lower_case=False, strip_punct=True)
    'AI ML rocks'
    >>> normalize_string_for_search("What's up, Doc?", lower_case=True, strip_punct=False)
    "what's up, doc?"
"""

描述更精确了（"非字母数字、非空白字符"），并带上了真正的 >>> 可执行示例，一眼就能看懂用法。它之所以理解了"search purposes"的语境，是因为作者明确告诉了它。

提示工程（Prompt Engineering）是指通过精心设计输入文本来引导大语言模型产出目标质量结果的方法论。其中"少样本提示"（Few-shot Prompting）是核心技巧之一：在提示词中直接给出若干输入-输出配对示例，让模型从示例中"读懂"任务规格，而无需依赖抽象描述。这与传统机器学习里的"微调"不同——它不修改模型权重，只在推理阶段通过上下文约束输出分布。本文作者的有效策略本质上正是少样本提示的应用：三组具体的 input-output 对充当了隐式的规格说明，让模型将"归一化"这个模糊概念锚定到可验证的行为上，而非凭借训练数据里的统计倾向自由发挥。

关键启示：AI 是副驾，不是自动驾驶

这个案例最大的价值，是揭示了一个被普遍忽视的提示工程原则：用具体的输入输出示例，比用抽象的形容词更能约束模型行为。当你要求 AI"更具体""更有用"时，这些词对模型几乎没有可操作的信息量；而三组真实的 input-output 对，直接告诉了它什么叫"成功"。

这也解释了为什么单纯升级到 gpt-4 并不能解决问题。模型能力的提升无法弥补上下文的缺失——函数背后的意图往往不写在代码里，而是藏在开发者的脑子里。你不把它说出来，再强的模型也只能靠猜。

从工作流角度看，这套方法的性价比值得权衡。前期需要额外花精力摸索提示策略，并为每个函数手写几个关键示例，但一旦模式固定，就能相对快速地批量处理那些积压已久的无文档函数：写几个示例，连同函数一起喂给 AI，拿到一份扎实的初稿。

它不是完全自动化——复杂函数仍需人工微调，但作为"文档副驾"确实高效。对于那些长期拖欠文档债的工具函数仓库，这是一条务实的还债路径。真正该记住的一点是：想从 AI 这里拿到"金子"而非"水货"，你得先把自己想要的样子，具体地展示给它看。