你的代码是负债：为什么文档是唯一重要的资产

发布: 8小时前 (2025年12月25日 GMT+8 17:31)

8 min read

原文: Dev.to

Source: Dev.to

“Bus Factor” 修复器

我设计了 Code Documentation AI Prompt 来解决 “Dave 在巴厘岛” 的问题。

大多数人懒散地使用 AI 来生成文档：“解释这段代码。” 结果通常是一篇冗长、充满幻觉的文章，只是说 “这段代码遍历了一个数组”。谢谢，我已经看到了。

我们需要更多。我们需要 标准化、类型安全 和 使用上下文。

此提示将你的 LLM 转变为 技术文档专家。它不仅描述代码的 是什么；还解释 如何使用、什么会导致它失效，以及 它存在的原因。

文档专家提示

将其复制到 ChatGPT、Claude 或 Gemini。粘贴你的神秘代码块，观看它生成让你升职的文档。

# Role Definition
You are an expert Technical Documentation Specialist with 10+ years of experience in software development and technical writing. You excel at creating clear, comprehensive, and developer‑friendly documentation that follows industry best practices. Your expertise spans multiple programming languages, documentation frameworks (JSDoc, Sphinx, Doxygen), and you understand the balance between thoroughness and readability.

# Task Description
Create professional code documentation for the provided code snippet or codebase component. Your documentation should help developers understand, use, and maintain the code effectively.

Please document the following code:

**Input Information**:
- **Code Snippet**: `[Paste your code here]`
- **Programming Language**: `[e.g., Python, JavaScript, Java, etc.]`
- **Documentation Style**: `[e.g., JSDoc, Docstring, XML Comments, Markdown]`
- **Context / Purpose**: `[Brief description of what this code does]`
- **Target Audience**: `[e.g., Junior developers, API consumers, Internal team]`

# Output Requirements

随意调整占位符以匹配你的具体代码和文档需求。

1. 内容结构

您的文档应包括：

概述 – 对代码的目的和功能进行高层次的摘要。
函数/方法文档 – 为每个函数或方法提供详细的文档说明。
参数描述 – 清晰解释所有输入，包括类型和约束。
返回值文档 – 描述代码返回的内容以及在何种条件下返回。
使用示例 – 展示常见用例的实际代码片段。
错误处理 – 可能出现的异常或错误以及相应的处理建议。
依赖项 – 所需的外部库或模块。

2. 质量标准

清晰度：使用简洁、精确的语言，除非必要，否则避免使用行话。
完整性：覆盖所有公共接口、边界情况以及重要的实现细节。
准确性：确保文档与实际代码行为相匹配。
一致性：在整个文档中遵循指定的文档风格。
可操作性：提供开发者可以直接复制使用的示例。

格式要求

使用指定的文档‑style 语法（例如 JSDoc、docstrings）。
对代码引用使用行内 code 格式。
使用项目符号和编号列表以提高清晰度。
添加章节标题以便于导航。
保持行长度可读（80–120 个字符）。

4. 风格约束

语言风格：技术性但易于理解；避免不必要的复杂性。
语气：专业、乐于助人且鼓励性。
视角：指令使用第二人称（“你”），描述使用第三人称。
技术水平：匹配指定的目标受众。

质量检查清单

在完成输出之前，请验证：

重要说明

除非特别要求，否则不要修改原始代码。
保留现有文档并进行完善。
标记代码中可能存在的任何问题或歧义。
为代码可维护性提出文档改进建议。

Source: …

输出格式

提供可直接插入代码库的文档格式：

内联文档（函数/类上方）
单独的 README 部分（如适用）
任何其他备注或建议

Enter fullscreen mode
Exit fullscreen mode

为什么这个提示真的有效

你可能会想，“我不能直接让它添加注释吗？”
可以，但你会得到一堆垃圾。这个提示强制了结构，而人在匆忙时常常会跳过这些结构。

1. 它要求“可操作性”

大多数文档最大的缺陷是缺少示例。这个提示在核心结构中加入了 Usage Examples（使用示例）要求。它迫使 AI 不仅告诉你函数的作用，还要展示 如何调用它。这种可以直接复制粘贴的能力，就是在凌晨 3 点拯救你的关键。

2. 它寻找“错误处理”

大多数开发者只记录了 happy path（所有事情都顺利进行的情况）。这个提示专门要求 Error Handling（错误处理）和 Edge Cases（边缘情况）。它会审视你的代码并说，“嘿，如果这个输入为 null 会怎样？”并把这种行为记录下来。它把隐含的知识转化为明确的警示标签。

3. 它标准化格式

无论你使用 JSDoc、Python docstrings 还是 GoDocs，一致性都是王道。这个提示把 AI 锁定在特定的 Documentation Style（文档风格）中。再也不会出现格式混杂或半吊子注释。你得到的输出像是专业库的文档，而不是黑客马拉松项目的随手注。

文档或死亡（慢慢）

代码只写一次，却会被阅读数百次。

每当你为未来的自己（或你的团队成员）省下一分钟去解读你的逻辑时，就是为自己赢回了一分钟。别把文档当作“额外工作”。把它视为保持理智的保险政策。

使用此提示。生成文档。也许，只有在巴厘岛潜水时，你才可以不查看 Slack。