生成有價值的文檔註解
代碼要交付或開源，需要寫註解但不想寫成廢話。
提示詞長度
172
tokens
建議模型
Flash
單次成本（離峰）
$0.00021
Flash
跑一萬次
$2.06
Flash 離峰
提示詞全文
為下面的函數寫文檔註解。
代碼：
```
{{代碼}}
```
風格：{{Google / NumPy / JSDoc / 中文}}
要求：
- 第一行說明「這個函數做什麼」，而不是「這個函數的定義」
- 參數說明要包含：類型、是否可為空、邊界條件
- 返回值說明包含：什麼情況下返回什麼
- 必須包含一個使用範例（能直接跑）
- 如果函數會拋出異常，逐個說明觸發條件
- 如果有副作用（改全域變數、寫檔、發請求），明確標出
禁止：
- 不要寫「詳見代碼」這類無資訊量的話
- 不要把函數名換句話說當成說明
為什麼這樣寫
- 「不要換句話說函數名」直接針對最常見的垃圾註解：`getUser()` → 「獲取用戶」。
- 要求標注副作用非常重要 —— 這是讀代碼的人最容易踩的坑。
- 要求可執行的範例，確保註解是準確的（寫錯的範例很容易被發現）。
成本
按上面這段提示詞估算（輸入 172 tokens、輸出 300 tokens）。輸出長度依任務而定，實際會有差異。
| 模型 | 單次（高峰） | 單次（離峰） | 1 萬次（高峰） | 1 萬次（離峰） |
|---|---|---|---|---|
| DeepSeek Flash | $0.00041 | $0.00021 | $4.12 | $2.06 |
| DeepSeek V4 Pro | $0.00142 | $0.00071 | $14.15 | $7.08 |
模型建議：註解生成是模式化任務，Flash 足夠。輸出量較大時用 Flash 能省下可觀成本。
變體
- 開源專案時，追加「同時生成 README 中的 API 說明段落」。
- 要生成類型定義時，追加「輸出對應的 TypeScript 型別或 Python type hints」。
常見失敗
- 不禁止無資訊量的話，會得到一堆「該函數用於處理數據」這種廢話。
- 不要求標副作用，純函數與有副作用的函數看起來會一樣。