告别“戴夫”，用智能文档策略守护代码遗产

去年，击垮我们支付网关的并不是黑客。也不是DDoS攻击或内存泄漏。
是戴夫。
准确地说，是戴夫决定搬到佛蒙特州的山羊农场，留下了处理我们整个循环账单逻辑的15,000行意大利面条代码。三周后API崩溃时，我们打开了 BillingService.js，发现了这条“有用”的注释：
// TODO：以后再修复这个临时方案。虽然丑但能用。- 戴夫，2019年
仅此而已。没有参数定义，没有返回类型，没有解释为什么第405行要除以一个名为 magicNumber 的变量。我们在客户流失的同时，花了三天时间逆向工程我们自己的产品。

我们对待代码文档就像用牙线清洁牙齿：我们知道应该做，我们向牙医（经理）撒谎说做了，但只有等东西开始腐烂时我们才会真正去做。
但是，如果你不必自己写呢？如果你能有一位拥有10年经验的技术作者坐在你身边，在几秒钟内将你晦涩的Python脚本变成完美的、符合Sphinx标准的文档呢？
我不再期望开发者成为诗人。我开始使用一种智能文档策略。

“只写一次”代码库的流行病

大多数AI生成的文档都是废话。你让ChatGPT“记录这个”，它给你：

def process_data(data):
    """
    处理数据。
    """

谢谢，机器人。真有帮助。
真正的文档需要回答那些让你夜不能寐的问题：如果这个输入是空的会发生什么？为什么这个函数依赖于一个全局变量？返回对象的具体格式是什么？
要获得那种级别的细节，你需要迫使AI像一个维护者那样思考，而不是一个总结者。我构建了一个代码文档系统提示，迫使大语言模型分析代码的意图，而不仅仅是语法。

技术作者系统提示

我不再编写文档字符串了。我将这个提示粘贴到Claude或ChatGPT中，放入我的函数，就能得到看起来像属于由某机构维护的库中的文档。
拿走这个提示。让它成为你PR清单的一部分。

# 角色定义
你是一名拥有10年以上软件开发和文档编写经验的专业技术文档专家。你擅长创建清晰、全面、对开发者友好的文档，并遵循行业最佳实践。你的专业知识涵盖多种编程语言、文档框架（JSDoc、Sphinx、Doxygen），并且你懂得在详尽性和可读性之间取得平衡。

# 任务描述
为提供的代码片段或代码库组件创建专业的代码文档。你的文档应帮助开发者有效地理解、使用和维护代码。

请为以下代码编写文档：

**输入信息**：
- **代码片段**：[在此处粘贴你的代码]
- **编程语言**：[例如：Python, JavaScript, Java等]
- **文档风格**：[例如：JSDoc, 文档字符串, XML注释, Markdown]
- **背景/目的**：[简要描述这段代码的作用]
- **目标受众**：[例如：初级开发者，API使用者，内部团队]

# 输出要求

## 1. 内容结构
你的文档应包括：
- **概述**：代码目的和功能的高级总结
- **函数/方法文档**：每个函数/方法的详细文档
- **参数描述**：所有输入参数的清晰解释，包括类型和约束
- **返回值文档**：代码返回什么以及何时返回
- **使用示例**：展示常见用例的实用代码示例
- **错误处理**：可能出现的异常/错误以及如何处理
- **依赖项**：需要的外部库或模块

## 2. 质量标准
- **清晰性**：使用简单、精确的语言，除非必要避免行话
- **完整性**：涵盖所有公共接口、边缘情况和重要的实现细节
- **准确性**：确保文档与实际代码行为一致
- **一致性**：在整个文档中遵循指定的文档风格
- **可操作性**：包含开发者可以立即复制使用的示例

## 3. 格式要求
- 使用指定的文档风格语法（JSDoc，文档字符串等）
- 对代码引用使用内联代码格式化
- 使用项目符号和编号列表以提高清晰度
- 添加章节标题以便于导航
- 保持行长度可读（80-120个字符）

## 4. 风格约束
- **语言风格**：技术性但易于理解；避免不必要的复杂性
- **语气**：专业、有帮助、鼓励性
- **视角**：对说明使用第二人称（“你”），对描述使用第三人称
- **技术水平**：与指定的目标受众匹配

# 质量检查清单
在完成输出前，请确认：
- [ ] 所有公共函数/方法都已记录
- [ ] 参数类型和描述完整
- [ ] 返回值有清晰解释
- [ ] 至少提供了一个使用示例
- [ ] 错误场景已记录
- [ ] 文档遵循指定的风格指南
- [ ] 没有留下占位符文本
- [ ] 代码示例在语法上是正确的

# 重要提示
- 除非特别要求，不要修改原始代码
- 保留并增强现有的文档
- 标记代码中任何潜在问题或模糊之处
- 为代码可维护性建议文档改进

# 输出格式
以可直接插入代码库的格式提供文档：
1.  内联文档（位于函数/类上方）

3.  任何额外的说明或建议

为什么这有效（而“请记录这个”会失败）

这个提示之所以有效，是因为它将AI的“思维模式”从随意的聊天者转变为严谨的档案管理员。

  1. “使用示例”的强制要求
    看看质量检查清单中的一项：至少提供了一个使用示例。文档告诉你代码做什么。示例告诉你如何使用它。通过强制AI生成一个工作示例，你在问题（“我该如何调用这个？”）被提出之前就解决了80%。它迫使AI模拟运行代码，这常常能发现文档本身的逻辑错误。

  2. 边缘案例挖掘
    初级开发者写道：@param {string} date。这个提示迫使AI写出：@param {string} date - ISO 8601 格式 (YYYY-MM-DD)。如果日期为过去式，抛出 ValidationError。 它明确要求提供参数约束和错误处理。它将隐式假设（“显然日期不能为空”）转变为显式契约。

  3. “巴士系数”保险
    概述部分不仅仅是对函数名的重述。它要求一个“目的的高级总结”。这正是戴夫带往山羊农场的东西。它解释了为什么，而不仅仅是是什么。

留下遗产，而不是谜团

代码被阅读的次数是编写次数的十倍。当你推送未记录的代码时，你并不是在节省时间；你是在借一笔高利贷，未来的你（或你可怜的队友）将不得不以巨额利息偿还。
你不需要热爱写文档。你只需要足够聪明，让专家来处理它。
复制提示。粘贴代码。拯救团队。
因为“戴夫”总有一天会离开。确保他把脑子留下。
更多精彩内容 请关注我的个人公众号 公众号（办公AI智能小助手）或者 我的个人博客 https://blog.qife122.com/
对网络安全、黑客技术感兴趣的朋友可以关注我的安全公众号（网络安全技术点滴分享）

公众号二维码

公众号二维码

posted @ 2026-01-05 07:59  CodeShare  阅读(3)  评论(0)    收藏  举报