你有沒有經歷過這種“靈魂出竅”的時刻：
盯着一段三個月前自己親手寫的代碼，感覺像是在看外星文明留下的天書。邏輯極其精妙，變量名簡寫得極其瀟灑，但你就是死活想不起來——這玩意兒到底是用來幹嘛的？
如果説寫代碼是構建一座宏偉的宮殿，那麼寫註釋就是給這座宮殿繪製“導遊圖”。遺憾的是，在趕進度的修羅場裏，我們往往只顧着添磚加瓦，卻忘了留下任何文字線索。
最終，項目變成了一座“數字迷宮”。新來的同事在裏面暈頭轉向，接手的維護者在裏面步步驚心，就連始作俑者你自己，過段時間回來也是一臉茫然。
🏺 打破“代碼即文檔”的迷思
在程序員圈子裏，流傳着一個迷人的謊言：“好的代碼是自解釋的（Self-documenting），不需要註釋。”
這句話只對了一半。
對於 getUserName() 這種顯而易見的代碼，註釋確實是噪音。
但對於那些反直覺的業務邏輯、為了性能的Hack寫法、以及複雜的算法實現，代碼本身只能告訴你“它做了什麼”，卻永遠無法告訴你“為什麼要這麼做”。
缺失的註釋，就是團隊的“知識債務”。債務是有利息的，而利息的支付方式，就是無休止的 Bug 排查和高昂的溝通成本。
🧩 AI：你的“羅塞塔石碑”雕刻師
如果是以前，我會勸你：“兄弟，咬咬牙，把文檔補上吧。”
但現在，作為一名追求極致效率的工程師，我會説：“這種要把邏輯翻譯成人類語言的活兒，為什麼不交給最擅長處理自然語言的 AI 呢？”
我為你準備了一套「代碼註釋生成 AI 指令」。
它不是簡單的“翻譯機”，而是一位“代碼考古學家”。它能深入分析你的代碼邏輯，推斷設計意圖，並用最規範的格式，為你刻下清晰的“羅塞塔石碑”。
🛠️ 複製這個指令，重塑代碼可讀性
這套指令的精髓在於“分層解析”。它會根據你指定的規範（JSDoc/Javadoc等），自動區分接口契約（參數/返回值）和實現細節（行內邏輯），確保註釋既不冗餘，也不缺失。
# 角色定義
你是一位資深代碼文檔工程師，擁有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 並説明替代方案
- 敏感信息（如密碼、密鑰）不要在註釋中出現
# 輸出格式
請直接輸出帶有完整註釋的代碼，使用對應語言的代碼塊格式。如果有多個文件，請分別標註文件名。
⚡️ 效果實測：從“天書”到“教科書”
讓我們來看一個真實的反直覺場景。
這是一段用於處理防抖（Debounce）的 JavaScript 代碼。如果不看註釋，你需要在大腦裏模擬半天 Event Loop 才能看懂它是怎麼工作的。
使用前（裸奔版）：
function debounce(func, wait, immediate) {
let timeout;
return function() {
const context = this, 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);
};
}
使用指令後（教科書版）：
/**
* 創建一個防抖函數，在指定時間內多次調用只執行一次
*
* 防抖常用於處理頻繁觸發的事件，如窗口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);
};
// 判斷是否需要立即執行：immediate 為 true 且當前沒有等待中的定時器
const callNow = immediate && !timeout;
// 每次調用都重置定時器，實現"重新計時"效果
clearTimeout(timeout);
timeout = setTimeout(later, wait);
// 立即執行模式下，首次調用直接執行
if (callNow) func.apply(context, args);
};
}
注意到了嗎？AI 不僅解釋了參數，還解釋了實現原理（如 "保持原函數的 this 指向"）。這不僅是文檔，更是教學。
💡 工程師的第二大腦
使用這個 AI 指令，並不是為了讓你偷懶，而是為了讓你把寶貴的腦力從“解釋代碼”中解放出來，去專注於“設計代碼”。
試着把這個指令集成到你的工作流中：
- 接手遺留項目時：先用 AI 跑一遍核心模塊，快速生成“地形圖”。
- 提交 Code Review 前：用 AI 補全文檔，讓 Reviewer 少問幾個“這是啥”。
- 編寫開源庫時：一鍵生成標準 JSDoc/Javadoc，讓你的項目顯得更專業。
代碼是寫給機器執行的，但更是寫給人看的。
別讓你的代碼，成為下一個需要解密的“未解之謎”。
