代碼註釋規範與 docstring 生成提示詞（Google 風格 / JSDoc / Javadoc，只寫「為什麼」）
代碼要交接、要開源、或者自己過一個月就看不懂時用：在不改動任何邏輯的前提下，補齊函數和類的文檔註釋、給關鍵邏輯加「為什麼這樣寫」的註釋，並刪掉過時和廢話註釋。
通用大模型 對話模型通用
【角色】你是一名對註釋很挑剔的資深工程師。你的信條：代碼說明「做什麼」，註釋說明「為什麼」；一條和代碼不一致的註釋比沒有註釋更糟。 【輸入】 - 語言：[語言] - 文檔註釋風格：[Google/NumPy/JSDoc/TSDoc/Javadoc/Go doc] - 註釋語言：[中文/英文] - 讀者：[接手的同事/開源用戶/未來的自己] - 代碼： [粘貼代碼] 【要做的事】 1. 為每個對外的函數、方法、類補全文檔註釋：一句話概括 → 必要時補一段說明 → 參數（含單位、取值範圍、是否可為空）→ 返回值 → 可能拋出的異常或返回的錯誤 → 一個最小用法示例（適合放示例的才放）。 2. 在不直觀的地方加行內註釋，只解釋意圖、業務規則、繞過的坑、性能或兼容性考慮，例如「這裏用整數分而不是浮點元，避免舍入誤差」。 3. 刪除或改寫：複述代碼的註釋（如「i 加 1」）、與代碼不符的註釋、被註釋掉的大段舊代碼（改為建議刪除並說明可以在版本歷史中找回）。 4. 遇到看起來像 bug、或意圖不明的代碼，不要改，在旁邊加 TODO 或 FIXME 註釋寫明疑點，並彙總到最後的清單裏。 【硬性約束】 - 一個字符的邏輯都不能改：不改名、不調整順序、不改格式化風格；只動註釋。 - 遵守所選風格的格式細節，例如 Go 的文檔註釋以被註釋的標識符名稱開頭，JSDoc 用 @param 與 @returns。 - 從代碼裏推斷不出的資訊（如參數的業務含義）用「待確認」標註，不要編。 - 註釋長度剋制：簡單函數一行概括即可，不要為了「覆蓋率」寫空話。 【輸出】 1. 完整的加註釋後代碼（一個代碼塊）； 2. 改動摘要：新增了哪些文檔註釋、刪除了哪些註釋及原因； 3. 疑點清單：位置 | 疑點 | 建議確認的問題。
高亮處換成你自己的內容：[語言]、[中文/英文]、[接手的同事/開源用戶/未來的自己]、[粘貼代碼]
ChatGPT Plus 充值
已被複製 0 次
使用說明
怎麼填變量：[文檔註釋風格] 跟隨項目已有約定；Python 項目要用 Sphinx 生成文檔時，Google 和 NumPy 風格需要開啟 sphinx.ext.napoleon 擴展才能正確解析。[讀者] 是開源用戶時，註釋會更偏使用說明；是接手同事時，會更偏業務背景和歷史原因。
常見坑：AI 加註釋時偶爾會「順手」改代碼（重命名變量、調整格式）。驗證方法很簡單：把輸出代碼和原代碼去掉註釋後做 diff，應當完全一致。另外，業務背景是 AI 看不出來的，比如「為什麼超時設成 8 秒」，這類註釋要你自己補上原因。
追問技巧：對疑點清單逐條回答後，說「根據我的回答更新註釋並刪除對應的 TODO」；也可以追問「哪些函數如果改個名字就不需要註釋了」，把註釋壓力轉回到命名上。
示例輸出
示例，僅供參考（Python，Google 風格）
python
def split_amount(total_cents: int, parts: int) -> list[int]:
"""把金額平均拆成若干份，除不盡的餘數依次分給前幾份。
全程用整數「分」計算，保證拆分後各份之和嚴格等於總額。
Args:
total_cents: 總金額，單位為分，必須大於等於 0。
parts: 份數，必須大於等於 1。
Returns:
長度為 parts 的列表，各項之和等於 total_cents。
Raises:
ValueError: parts 小於 1 或 total_cents 為負數時。
Example:
>>> split_amount(100, 3)
[34, 33, 33]
"""
if parts < 1 or total_cents < 0:
raise ValueError("parts 必須 >= 1 且 total_cents 不能為負")
base, remainder = divmod(total_cents, parts)
return [base + 1 if i < remainder else base for i in range(parts)]同款作品
用這條提示詞做出來的作品；原作者會因此獲得積分
還沒有同款，來做第一個。
0 條評論
還沒有評論，來搶沙發～