想象這樣一個場景：
週五晚上 11 點，線上服務突然報警。你火急火燎地打開 IDE，定位到報錯的 UserUtils.java，映入眼簾的是一個長達 800 行的 processData 函數。
沒有文檔，沒有註釋。
唯一的線索是第 3 行的一句：// 這裏的邏輯有點亂，改動前先問問老王。
而不幸的是，老王已經在三個月前離職回老家養豬了。
此刻的你，是不是感覺血壓飆升，想順着網線過去找人？
這不僅僅是段子，這是每一個程序員都經歷過的"代碼考古"現場。我們常説代碼是寫給機器看的，但實際上，代碼更是寫給人看的——是寫給三個月後的自己，也是寫給接手你工作的"倒黴蛋"。
為什麼我們不愛寫註釋？
誰都知道註釋重要，但為什麼代碼庫裏還是充斥着大量的"無字天書"？
- 太懶："代碼即文檔，我變量名取得好，不需要註釋。"（真的嗎？那個
flag1和temp_data是什麼鬼？） - 太忙："業務都在催，哪有時間寫作文？功能跑通就行了。"
- 怕過時："代碼改了，註釋忘了改，比沒註釋更坑。"
於是，我們的項目就變成了一座座迷宮，只有當初的建造者知道出口在哪裏。一旦建造者離開，迷宮就變成了"死局"。
請一位 24 小時在線的"文檔翻譯官"
如果有一個助理，能盯着你寫的每一行代碼，自動幫你補全清晰、規範、通過率極高的註釋，甚至還能幫你解釋那些複雜的算法邏輯，你會拒絕嗎？
今天分享的這套 AI 代碼註釋生成指令，就是你的"御用文檔翻譯官"。
它不只是簡單地翻譯代碼，它能理解你的設計意圖。它遵循 JSDoc、Javadoc 等專業規範，把冰冷的代碼邏輯，轉化為有温度的人類語言。
📋 代碼註釋生成 AI 提示詞
# 角色定義
你是一位資深代碼文檔工程師，擁有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 並説明替代方案
- 敏感信息（如密碼、密鑰）不要在註釋中出現
# 輸出格式
請直接輸出帶有完整註釋的代碼，使用對應語言的代碼塊格式。如果有多個文件，請分別標註文件名。實戰：把"天書"變成"説明書"
口説無憑，我們來個現場演示。
假設你寫了一個 Python 的 LRU 緩存類，邏輯稍微有點繞。直接丟給 AI，不需要你説廢話，它會還你一份教科書級別的代碼：
AI 輸出效果：
class LRUCache:
"""
LRU (Least Recently Used) 緩存實現類
基於 OrderedDict 實現的 LRU 緩存，自動淘汰最久未使用的數據。
常用於內存緩存、數據庫查詢緩存等需要限制緩存大小的場景。
Attributes:
capacity (int): 緩存最大容量
cache (OrderedDict): 有序字典，用於存儲緩存數據
"""
def __init__(self, capacity: int) -> None:
"""
初始化 LRU 緩存
Args:
capacity: 緩存最大容量，必須為正整數
"""
self.capacity = capacity
self.cache = OrderedDict()
def get(self, key: Any) -> Any:
"""
獲取緩存值，並將該鍵標記為最近使用
Returns:
緩存值，如果鍵不存在則返回 -1
"""
if key not in self.cache:
return -1
# 將訪問的鍵移到末尾，表示最近使用
self.cache.move_to_end(key)
return self.cache[key]看到區別了嗎？
- Docstring: 它是怎麼實現的？（基於 OrderedDict）
- Args/Returns: 傳什麼參？回什麼值？（一目瞭然）
- Inline Comment: 為什麼要
move_to_end？（標記為最近使用）
這不僅是給別人看的，更是給你自己梳理邏輯的過程。
別讓代碼成為你的"獨家記憶"
很多時候，我們覺得寫註釋是浪費時間，是因為我們把"寫代碼"和"寫文檔"割裂開了。
但在這個 AI 輔助編程的時代，註釋即代碼的一部分。
試着把這個指令放進你的收藏夾（或者 Prompt 庫）。下次提交代碼前，花 10 秒鐘跑一下這個指令。這 10 秒鐘，可能會挽救三個月後那個在凌晨排查 Bug 的你自己。
畢竟，我們寫下的每一行註釋，都是給未來的自己留的一盞燈。
