用 AI 寫技術文件與程式註解：從 README 到 API 文件的高效寫法

文件是工程師的痛，也是 AI 的強項

幾乎每位工程師都同意文件很重要，但真正願意花時間寫的沒幾個。結果就是：README 過時、API 沒有文件、函式沒有註解，新人接手時只能靠讀原始碼硬啃。AI 助手在這件事上特別有用，因為寫文件本質是「把已知的邏輯轉成清楚的文字」，這正是語言模型的強項。你把程式碼給它，它能快速產出結構完整、語句通順的文件。

但用 AI 寫文件也有陷阱：它可能寫出「聽起來對但其實不準」的內容，或是過度註解每一行造成雜訊。本文教你怎麼用得對。

第一類：寫 README

README 是專案的門面，好的 README 應該讓人在三分鐘內知道這是什麼、怎麼裝、怎麼用。你可以把專案的關鍵資訊給 AI，讓它產出結構化的 README。提問範例：

請幫我寫一份專案 README，專案資訊如下：
- 名稱：invoice-parser
- 功能：解析 PDF 發票，抽出金額、日期、賣方統編
- 語言：Python 3.12，用 pdfplumber
- 安裝：pip install -r requirements.txt
- 使用：命令列 python parse.py <pdf路徑>
請包含：簡介、功能特色、安裝、快速開始（含範例指令與輸出）、設定說明、授權。
用繁體中文，程式碼區塊用 markdown。

AI 會產出結構完整的草稿，你再補上它不知道的細節即可。這比從空白檔案開始快得多。要注意的是，AI 不知道你的真實安裝步驟與相依版本，這些一定要你自己核對，不能讓它憑空編造。

第二類：寫函式註解與 docstring

函式層級的文件是最實用的。以 Python 為例，把函式貼給 AI 並要求產生符合規範的 docstring：

def calculate_tax(income, deductions, is_resident=True):
    taxable = max(0, income - deductions)
    if is_resident:
        rate = 0.05 if taxable < 560000 else 0.12
    else:
        rate = 0.18
    return round(taxable * rate, 0)

提問：「請為這個函式加上 Google 風格的 docstring，說明參數、回傳值與計算邏輯，用繁體中文。」AI 會產出：

def calculate_tax(income, deductions, is_resident=True):
    """計算應繳所得稅額。

    Args:
        income (float): 年度總所得。
        deductions (float): 可扣除額總和。
        is_resident (bool): 是否為稅務居民，預設為 True。
            非居民適用單一較高稅率。

    Returns:
        float: 應繳稅額，四捨五入至整數。

    Note:
        居民採級距稅率，課稅所得未達 56 萬適用 5%，
        達 56 萬以上適用 12%；非居民一律 18%。
    """
    taxable = max(0, income - deductions)
    ...

JavaScript 則用 JSDoc 格式：

/**
 * 計算購物車總金額，含運費與折扣。
 * @param {Array<{price: number, qty: number}>} items 商品清單
 * @param {number} shipping 運費
 * @param {number} [discount=0] 折扣金額，預設為 0
 * @returns {number} 應付總金額
 */
function calcTotal(items, shipping, discount = 0) {
  const subtotal = items.reduce((s, i) => s + i.price * i.qty, 0);
  return subtotal + shipping - discount;
}

第三類：寫 API 文件

如果你有一個 REST API，可以把路由與參數給 AI，讓它產出 API 文件或 OpenAPI 規格。提問範例：「這是一個建立訂單的 endpoint，請幫我寫 API 文件，包含 HTTP 方法、路徑、請求參數、請求範例、回應範例與錯誤碼。」附上你的 handler 程式碼，AI 就能整理成表格與範例。這對前後端協作特別有用，能省下大量溝通成本。

註解的黃金原則：解釋為什麼，而非做什麼

這是最重要的觀念。很多人（包括 AI）會寫出這種註解：

i = i + 1  # 把 i 加 1

這種註解毫無價值，因為程式碼本身已經說明了「做什麼」。好的註解應該解釋「為什麼」，也就是程式碼看不出來的意圖與背景。例如：

# 加 1 是因為外部 API 的頁碼從 1 開始，我們內部從 0 起算
page = index + 1

所以用 AI 寫註解時，要明確要求它：「只在邏輯不明顯、有特殊考量或容易誤解的地方加註解，解釋為什麼這樣做，不要逐行翻譯程式碼。」否則 AI 傾向每行都註解，反而製造雜訊，降低可讀性。過度註解和沒有註解一樣有害。

確保文件與程式碼同步

文件最大的敵人是「過時」。程式改了，文件沒改，就會誤導後人，比沒有文件還糟。用 AI 有幾個維持同步的技巧：

第一，改程式時順手把新舊程式碼一起給 AI，請它更新對應的文件與註解。第二，在 code review 時把文件變更也納入審查範圍，程式改了卻沒改文件就要退回。第三，讓文件盡量靠近程式碼，例如用 docstring 而非獨立的 Word 檔，這樣改程式時比較不會忘記改文件。第四，定期請 AI 做一致性檢查：「這份 README 的使用範例，和目前的 CLI 參數一致嗎？」把 README 與程式碼一起貼給它比對。

驗證 AI 產出的文件準確性

AI 寫文件最大的風險是「言之鑿鑿地寫錯」。它可能描述一個不存在的參數，或把預設值寫錯。所以每份 AI 產出的文件都要驗證：範例指令真的能跑嗎？參數說明和程式碼一致嗎？回應範例的欄位是真的嗎？最可靠的驗證方式，就是照著文件實際操作一遍。如果文件裡的快速開始範例你自己跑一次會失敗，那對讀者就是災難。

實用工作流總結

把以上整合成一個實用流程：寫新功能時，先寫程式，再把程式貼給 AI 產生 docstring 與 README 更新草稿；自己核對準確性，修掉編造與過度註解；送 PR 時把文件變更一起審；改程式時同步更新文件。長期維持下來，你的專案文件品質會遠勝過大多數團隊，而花的力氣卻不多。

小結

AI 讓寫文件從苦差事變成幾分鐘的事，特別適合產生 README、docstring、JSDoc 與 API 文件的骨架。但兩個原則不能忘：註解要解釋為什麼而非做什麼，避免過度註解；文件必須驗證準確並與程式碼同步。把 AI 當成寫作助手，自己守住準確性這道關，就能讓文件真正發揮價值。