AI生成文档字符串翻车实录：遗留Python代码的混合工作流

接手一个遗留Python项目，满屏未注释的函数和晦涩的单行代码，很多人第一反应是：让AI来批量生成docstring。一位独立开发者的真实经历却给出了不同答案——AI直接生成的结果充斥着泛泛而谈甚至凭空捏造，真正有效的方案是把AI从「创作者」降级为「润色者」。

第一步：把整个仓库丢给AI的幻想

这位开发者的目标很明确：为每个函数、类和方法生成Google风格的docstring，不仅格式统一，还要准确说明代码做了什么、参数含义和返回值。他先尝试了最直接的方式——在VS Code中打开GitHub Copilot，或用ChatGPT 4o输入「为这个函数生成Google风格docstring」，然后粘贴函数代码。

以一个发票计算函数为例，AI给出的docstring在格式上没问题，参数和返回值都写对了，但完全没有提及代码中实际支持的折扣码（SAVE10、FREESHIP），也没有说明FREESHIP分支只是打标记、真正的运费逻辑在别处。这种「模板化」的输出看起来能用，实际上丢失了遗留代码最需要传递的业务上下文。

Google风格docstring是一种广泛采用的Python文档字符串规范，起源于Google内部的Python代码风格指南。它使用结构化的段落来描述函数行为，典型格式包含Args:（参数说明）、Returns:（返回值说明）和Raises:（异常说明）三个主要部分。每个参数以参数名 (类型): 描述的形式列出，返回值则说明类型和含义。相比reStructuredText（Sphinx使用）和NumPy风格，Google风格在保持结构化的同时可读性更强，尤其适合阅读源码时快速定位信息。许多文档生成工具如Sphinx（通过napoleon扩展）、pydocstyle等都能解析这种格式。正因如此，开发者希望遗留代码统一采用这种风格，以便后续自动生成API文档。然而格式规范只是外壳，真正的难点在于填充准确的业务语义。

第二步：复杂逻辑面前的幻觉与不一致

真正的问题出现在处理复杂函数时。AI开始编造不存在的参数、声称函数返回布尔值而实际返回字典、或者完全误解某个条件分支的用途。

一个典型场景是process_user_data(user_id, config)这样的函数——config是一个深层嵌套字典，在系统中被到处传递，缺少键时容易出错。AI生成的描述只会写「config: 用户配置设置」，技术上没错，但对理解哪些键是必需的、结构长什么样毫无帮助。

开发者花了大约3个小时反复调整提示词，要求AI「更具体」「仔细分析代码」，但输出质量极不稳定：一个docstring冗长啰嗦，下一个又过于简略。AI在生成「某种」docstring，但不是「他的」docstring，也不是不经逐行审查就能信任的准确文档。

大语言模型的幻觉（hallucination） 是指模型生成看似合理但与事实不符的内容。在代码文档场景中，幻觉表现为编造不存在的参数、错误声明返回类型、或凭空假设函数的功能。其根源在于：LLM本质上是基于概率预测下一个token，而非真正"理解"代码的执行逻辑。当函数体较短、模式常见时，模型能较准确推断；但面对深层嵌套的数据结构、跨模块的隐式依赖、或高度定制化的业务分支时，模型缺乏足够上下文来准确推理，便倾向于用训练数据中的常见模式来"填补空白"。这就是为什么AI会声称一个返回字典的函数返回布尔值——因为在它的训练分布中，命名相似的函数往往返回布尔值。理解这一点有助于判断何时该信任AI输出、何时必须人工核验。

第三步：人写核心、AI补结构的混合流程

转折点在于重新定位AI的角色：它在复杂陌生代码中的优势不是「创造」，而是给定扎实起点后的「精炼」和「统一」。新的工作流分三步：

人先写核心想法。 每个函数先花30秒到1分钟，基于对代码和业务逻辑的理解，手写一两句话说明它到底做什么，手动识别参数及其含义。

AI负责结构扩展。 把函数和这段粗略描述一起交给ChatGPT 4o，提示词明确要求「准确描述参数、返回值和可能的异常，保持Google docstring格式一致」。对于user_permissions或config这类棘手的参数，还会额外补充一段上下文说明。AI此时能产出相当完善的docstring，包括权限校验逻辑、PermissionError和ValueError等异常说明。

人工审查纠错。 这一步不可省略。逐项核对参数类型、返回值和描述是否与实际代码逻辑吻合，经常能发现int被写成str、遗漏的None返回等情况。由于已有AI生成的完整结构，这一步比从零手写或反复调试全自动模式快得多。

Force multiplier（力量倍增器） 是一个源自军事战略的概念，指能够显著放大现有资源效能的工具或方法。在AI辅助编程语境中，它意味着AI并不替代人类判断，而是将人类的专业能力放大数倍。与之相对的是autopilot（自动驾驶） 模式——完全放手让AI独立完成任务。文章的核心洞见在于：对于docstring生成这类需要深层业务理解的任务，AI作为force multiplier效果显著，因为人类提供了AI所缺乏的业务上下文和准确性判断，AI则贡献了格式化、结构化和语言组织能力。但若将其当作autopilot，让AI从零生成文档，则幻觉和泛泛而谈将不可避免。这一区分对理解当前AI编程工具的能力边界具有普遍指导意义：AI最有效的使用方式往往是增强而非替代人的专业判断。

效率提升与边界认知

据这位开发者统计，混合方法将docstring生成时间减少了约60%到70%，产出的结果也比让AI全自动运行更加一致和准确。

这个案例揭示了一条对AI编程有普遍意义的边界：当任务需要深层上下文理解和绝对准确性时，尤其是在不熟悉的代码库中，人类仍然必须留在回路里。AI不是银弹，但它确实能把这条回路缩短很多。把AI当作force multiplier而非autopilot，或许是当前阶段与代码助手协作的最务实姿态。