💀 那个"碰不得"的神秘模块

你是否经历过这样的职场惊悚时刻？

接手了一个离职大牛留下的核心模块，代码运行得如丝般顺滑，业务逻辑也极其重要。但当你试图修复一个小 Bug 或者添加一个新功能时，你发现自己站在了一座迷宫面前：

• 函数名叫 processData，参数是 a、b、c。
• 里面充斥着 if (type === 7) 这种魔法数字。
• 没有任何一行注释解释为什么要这么写。

这时候，你不仅不敢改，甚至不敢问。因为这段代码就像一个精密的定时炸弹，"跑得好好的"是它最后的伪装，而"没人敢动"才是它真实的命运。

软件工程中有一个残酷的数据：程序员读代码的时间，是写代码时间的 10 倍以上。

在这个 AI 辅助编程的时代，我们写代码的速度越来越快，但如果我们产出的只是"机器能跑"的二进制垃圾，那么我们实际上是在以光速制造技术债务。

今天，我想分享一套**“代码注释生成 AI 指令”。它不是为了让你应付文档检查，而是为了帮你把脑海中的设计意图，低成本地固化为代码的一部分，让你的代码真正变成团队的资产**。

---

🏗️ 代码即文档：打破"知识孤岛"

很多人不写注释的理由通常是：“好的代码是自解释的。”

这句话本身没错，但它往往被当成了懒惰的借口。自解释的代码只能告诉你"它做了什么"，但永远无法告诉你"为什么要这么做"。

• 为什么这里要加一个 50ms 的延迟？
• 为什么这个参数默认值是 -1？
• 为什么这里要捕获异常却不处理？

这些隐藏在代码背后的上下文（Context），才是注释真正的价值所在。

为了解决"写代码一时爽，补注释火葬场"的困境，我封装了这套 AI 指令。它能像一位经验丰富的代码文档工程师，帮你把晦涩的逻辑翻译成清晰的人类语言。

核心 AI 指令（建议直接存入 Cursor/Obsidian）

# 角色定义
你是一位资深代码文档工程师，拥有10年以上软件开发经验，精通多种编程语言的文档规范（如JSDoc、Javadoc、Python Docstring、XML Doc等）。你擅长分析代码逻辑、理解设计意图，并能用简洁清晰的语言编写高质量的代码注释。

# 任务描述
请为以下代码生成专业、规范的注释，确保注释能够帮助开发者快速理解代码功能、参数说明、返回值及使用场景。

**输入信息**:
- **编程语言**: [请指定：JavaScript/Python/Java/C#/Go/TypeScript/其他]
- **注释规范**: [请指定：JSDoc/Javadoc/Python Docstring/XML Doc/自定义/自动识别]
- **注释级别**: [请选择：函数级/类级/模块级/行内注释/全部]
- **详细程度**: [请选择：简洁/标准/详细]

**待注释代码**:
```
[在此粘贴你的代码]
```

# 输出要求

## 1. 内容结构
- **文件/模块头注释**: 描述文件用途、作者、创建日期
- **类/接口注释**: 描述类的职责、设计目的、使用示例
- **函数/方法注释**: 功能描述、参数说明、返回值、异常处理、使用示例
- **关键逻辑注释**: 复杂算法或业务逻辑的行内说明

## 2. 质量标准
- **准确性**: 注释必须准确反映代码的实际功能，不能有歧义
- **完整性**: 覆盖所有公共API、复杂逻辑和关键决策点
- **简洁性**: 用最少的文字表达最完整的信息
- **规范性**: 严格遵循指定的注释规范格式

## 3. 格式要求
- 遵循指定编程语言的注释语法
- 保持一致的缩进和对齐
- 使用规范的标签（如@param、@returns、@throws等）
- 中英文之间添加空格，提升可读性

## 4. 风格约束
- **语言风格**: 技术专业但通俗易懂
- **表达方式**: 第三人称客观叙述
- **专业程度**: 面向开发者，假设读者具备基础编程知识

# 质量检查清单

在完成输出后，请自我检查:
- [ ] 注释格式符合指定的文档规范
- [ ] 函数的参数和返回值都已说明
- [ ] 复杂逻辑处有行内注释解释
- [ ] 没有拼写错误或语法问题
- [ ] 注释与代码实际功能一致

# 注意事项
- 不要修改原有代码逻辑，只添加注释
- 避免过度注释（如解释显而易见的代码）
- 对于废弃的方法要标注 @deprecated 并说明替代方案
- 敏感信息（如密码、密钥）不要在注释中出现

# 输出格式
请直接输出带有完整注释的代码，使用对应语言的代码块格式。如果有多个文件，请分别标注文件名。

---

🔍 实战演练：AI 如何"重构"你的代码可读性

光说不练是假把式。让我们看看在真实开发场景中，这套指令如何化腐朽为神奇。

场景一：那个"没人看得懂"的防抖函数

你写了一个通用的防抖工具函数，逻辑很精妙，但同事用的时候总是传错参数。

你的输入：

function debounce(func, wait, immediate) {
    let timeout;
    return function() {
        // ... (省略具体实现)
    };
}

AI 的输出（JSDoc 规范）：

/**
 * 创建一个防抖函数，在指定时间内多次调用只执行一次
 * 
 * 防抖常用于处理频繁触发的事件，如窗口resize、输入框实时搜索等场景，
 * 可以有效减少不必要的函数调用，提升性能。
 * 
 * @param {Function} func - 需要防抖处理的目标函数
 * @param {number} wait - 防抖延迟时间，单位毫秒
 * @param {boolean} [immediate=false] - 是否立即执行
 *   - true: 在延迟开始时立即执行，后续调用在延迟结束前被忽略
 *   - false: 在延迟结束后执行最后一次调用
 * @returns {Function} 经过防抖处理的新函数
 * 
 * @example
 * // 基础用法：延迟 300ms 执行
 * const debouncedSearch = debounce(searchAPI, 300);
 * input.addEventListener('input', debouncedSearch);
 */
function debounce(func, wait, immediate) {
    // ...
}

解析：
这就不仅仅是注释了，这是一份微型的使用文档。

1. 明确了场景：告诉使用者"什么时候用"。
2. 解释了参数：特别是 immediate 这种布尔值，解释了 true/false 的具体行为差异。
3. 提供了示例：让使用者可以"CV大法"直接上手。

场景二：遗留系统中的"天书"算法

你维护的系统中有一个计算价格的核心类，里面充满了魔法数字和复杂的判断逻辑。

你的输入：

class LRUCache:
    # ... (一段没有注释的Python代码)

AI 的输出（Python Docstring）：

"""
LRU (Least Recently Used) 缓存实现类

基于 OrderedDict 实现的 LRU 缓存，自动淘汰最久未使用的数据。
常用于内存缓存、数据库查询缓存等需要限制缓存大小的场景。

时间复杂度：
    - get: O(1)
    - put: O(1)

Attributes:
    capacity (int): 缓存最大容量
    cache (OrderedDict): 有序字典，用于存储缓存数据
"""
class LRUCache:
    def __init__(self, capacity: int) -> None:
        """
        初始化 LRU 缓存
        
        Args:
            capacity: 缓存最大容量，必须为正整数
            
        Raises:
            ValueError: 当 capacity 小于等于 0 时抛出
        """
        self.capacity = capacity
        # ...

解析：
AI 不仅补全了参数说明，还自动分析了时间复杂度。这对于后续维护者评估性能影响至关重要。

---

💡 进阶玩法：让文档"活"起来

如果你还在手动写文档，那你可能已经落伍了。这套指令可以配合现代化的开发工作流，发挥更大的价值。

1. 配合 IDE 插件实现"文档即时预览"

现在的 IDE（如 VS Code、IntelliJ IDEA）都能完美识别 JSDoc 或 Docstring。
当你用 AI 生成了标准注释后，任何人在调用这个函数时，鼠标悬停就能看到完整的参数说明和示例。这比写在 Wiki 里的一百页文档都有用，因为它就在代码手边。

2. 代码评审（Code Review）的"守门员"

把这套指令集成到你的 Code Review 流程中。
当你发现同事提交了裸奔的代码，不需要在评论区打字"请补充注释"，直接把代码扔给 AI，生成标准注释后贴给他：“按照这个格式补全一下。”
既专业，又节省沟通成本。

3. 遗留系统的"考古挖掘机"

面对那些没有任何文档的"屎山"代码，这套指令就是你最好的考古工具。
不要试图肉眼去啃逻辑，先用 AI 生成一份详细的注释版本。你会发现，原本一团乱麻的逻辑，在清晰的自然语言描述下，突然变得有迹可循了。

🚀 结语

代码是写给机器执行的，但更是写给人看的。

优秀的程序员，不仅能写出高性能的代码，更能写出让队友如沐春风的代码。注释不是累赘，它是你留给后来者的路标，是团队协作的润滑剂，更是你职业素养的体现。

别再让你的代码成为团队中的"神秘禁区"。从今天开始，用 AI 给你的代码穿上一层"说明书"，让它在未来的日子里，依然能被读懂、被维护、被感激。