你有没有过这种经历：面对自己三个月前写的代码，感觉像是在看天书？
接手离职同事的"遗产"代码时，因为不仅没文档连注释都没有，恨不得当场重写？
Code Review时，为了搞懂一个复杂函数的意图，不得不把整个调用链翻个底朝天？
如果代码是程序员的孩子，那注释就是孩子的户口本和病历卡。可惜的是，在"赶进度"和"改Bug"的双重夹击下，写注释往往成了那个被最先牺牲掉的环节。
但后果也是显而易见的：代码写得越快，遗忘得越快；系统越复杂，维护成本越高。 最后，我们创造了无数只有上帝和当时的自己能看懂的"孤儿代码"。
现在，是时候让 AI 来终结这个恶性循环了。
我设计了一套"代码注释生成AI指令"，它不只是简单地翻译代码，而是像一位严谨的代码文档工程师，通过深度分析逻辑，自动为你的代码穿上规范、清晰的"防护服"。
🛡️ 你的代码守护者：核心AI指令
请将以下指令投喂给 通义千问 (Qwen)、DeepSeek 或 Kimi 等国产大模型。它们在理解中文技术语境和生成规范文档方面，有着惊人的表现。
# 角色定义
你是一位资深代码文档工程师，拥有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. 风格约束
- **语言风格**: 技术专业但通俗易懂
- **表达方式**: 第三人称客观叙述
- **专业程度**: 面向开发者，假设读者具备基础编程知识
# 质量检查清单
在完成输出后，请自我检查:
- [ ] 注释格式符合指定的文档规范
- [ ] 函数的参数和返回值都已说明
- [ ] 复杂逻辑处有行内注释解释
- [ ] 没有拼写错误或语法问题
- [ ] 注释与代码实际功能一致
# 输出格式
请直接输出带有完整注释的代码，使用对应语言的代码块格式。如果有多个文件，请分别标注文件名。
💊 疗效见证：从"裸奔"到"全副武装"
很多开发者觉得写注释是浪费时间，认为"好的代码能够自解释"。这句话在理想状态下没错，但在现实的屎山堆里，注释往往是救命稻草。
看看这套指令是如何化腐朽为神奇的。
案例：一个让人摸不着头脑的防抖函数
原始代码（裸奔版）：
function d(f, w, i) {
let t;
return function () {
const c = this, a = arguments;
const l = function() {
t = null;
if (!i) f.apply(c, a);
};
const cn = i && !t;
clearTimeout(t);
t = setTimeout(l, w);
if (cn) f.apply(c, a);
};
}
这代码能跑吗？能。你看得懂吗？可能得盯着看半分钟。变量名简写，逻辑嵌套，不仅难懂，还容易改坏。
AI处理后的代码（精装版）：
/**
* 创建一个防抖函数，在指定时间内多次调用只执行一次
*
* 防抖常用于处理频繁触发的事件，如窗口resize、输入框实时搜索等场景，
* 可以有效减少不必要的函数调用，提升性能。
*
* @param {Function} func - 需要防抖处理的目标函数
* @param {number} wait - 防抖延迟时间，单位毫秒
* @param {boolean} [immediate=false] - 是否立即执行
* - true: 在延迟开始时立即执行，后续调用在延迟结束前被忽略
* - false: 在延迟结束后执行最后一次调用
* @returns {Function} 经过防抖处理的新函数
*/
function debounce(func, wait, immediate) {
// 用于存储定时器ID，实现延迟控制
let timeout;
// 返回包装后的函数，保持原函数的 this 指向和参数
return function executedFunction() {
const context = this;
const args = arguments;
// 延迟执行的回调函数
const later = function() {
timeout = null;
// 非立即执行模式下，在延迟结束后调用目标函数
if (!immediate) func.apply(context, args);
};
// 判断是否需要立即执行
const callNow = immediate && !timeout;
// 每次调用都重置定时器，实现"重新计时"效果
clearTimeout(timeout);
timeout = setTimeout(later, wait);
// 立即执行模式下，首次调用直接执行
if (callNow) func.apply(context, args);
};
}
发现区别了吗？
- 功能一目了然：顶部的 JSDoc 清楚解释了这是干嘛的，甚至给出了应用场景。
- 参数清晰明了：
immediate参数的 true/false 逻辑解释得清清楚楚，不用再去猜。 - 逻辑透视：关键代码行（如
callNow的判断）都有行内注释，直接点破逻辑核心。
💡 为什么你需要这个"外挂"？
这不仅仅是为了偷懒，而是一种技术资产的保值手段。
- 降低交接成本：新同事入职，扔给他一份注释完善的代码，比你坐在他旁边讲一下午都要高效。
- 提升Review质量：代码评审时，大家可以聚焦在业务逻辑是否合理，而不是纠结"这个变量
t到底是代表 time 还是 type"。 - 倒逼代码质量：有时候 AI 无法生成清晰的注释，是因为你的代码逻辑本身就混乱。这时候，AI 其实是在提醒你：该重构了。
🚀 立即行动
别再让"没时间写注释"成为代码腐烂的借口。把这条指令收藏进你的 Prompt 库，下次写完核心逻辑后，花 10 秒钟让 AI 帮你做个"精装修"。
毕竟，写给机器看的代码只能运行，写给人类看的代码才能传承。
