Vibe Coding 方法論 · 第 4 節

註釋三要素與程式碼保護

AI 寫的註釋多是功能複述，三個月後回來看程式碼，想不起當初為什麼這樣實現。這一節給註釋立結構，也給「刪程式碼」立規矩。頁面裏有兩個可動手的演示。

問題在哪

程式碼只能表達「做了什麼」。為什麼存在、為什麼這樣實現、調用時要注意什麼，這些信息只有寫進註釋才能跨時間留存。「寫好註釋」四個字 AI 執行不了，必須給出固定結構和示例。

三要素結構

背景

這個函式為了解決什麼業務問題、在什麼場景下被調用。沒有背景，讀程式碼的人只能看到實現，看不到它為什麼存在。

設計意圖

為什麼這樣實現，選擇這種方案的理由，以及放棄了哪些備選方案。git log 裏找不到這些，註釋是唯一載體。

關鍵約束

調用方須知：副作用、依賴關係、邊界條件等非顯而易見的注意點。少了這條，下一個調用者就會踩坑。

互動演示一 · 同一個函式，兩種註釋

點擊切換同一個 merge_chat_history 函式的兩種註釋寫法，對比它們留下的信息量。

chat/history.py
          背景設計意圖關鍵約束
        
def merge_chat_history(existing: list, incoming: list) -> list:
    """
    合併兩個聊天記錄列表，返回合併後的結果。
    """
    ...
def merge_chat_history(existing: list, incoming: list) -> list:
    """
    背景：前端每次會話恢復時會帶上本地緩存的歷史消息，
    但服務端也保留了一份持久化記錄，兩者可能因網絡中斷出現分叉。
    設計意圖：以服務端記錄為權威，僅追加本地獨有的消息，
    不做全量替換，避免覆蓋掉服務端已有的 AI 回覆元數據。
    約束：incoming 中 role=system 的消息一律丟棄，不合併入結果。
    """
    ...

這條註釋複述了函式名，讀一眼程式碼就能得到同樣的信息。三個月後想知道「為什麼以服務端為權威」「為什麼丟棄 system 消息」，什麼綫索都沒有。

互動演示二 · 刪不刪，你來判

三個真實情景，判斷 AI 應該怎麼做。點選項即時判定，並給出對應的規則依據。

情景 1 · AI 在重構時發現一段兼容舊數據格式的程式碼，它覺得「看起來沒用」，想順手刪掉。

情景 2 · 重構後實現方式變了，原有的「設計意圖」註釋已經和程式碼對不上了。

情景 3 · AI 覺得 fetch 比 axios 更輕量，想把項目裏的 axios 換成 fetch，順手改掉 package.json。

已答對 0 / 3 題

兩條保護規則

註釋保護

重構時禁止以「註釋太長」「程式碼自解釋」「順便清理」為由刪除背景和設計意圖註釋。實現變了導致註釋不準確時，必須同步更新內容。判斷標準只有一條：之後接手嘅人，冇呢條註釋仲理唔理解當初點解要咁做？

程式碼刪除聲明

刪除任何已有功能程式碼前，必須明確告知用戶並説明理由，禁止以「順手清理」「看起來沒用」為由靜默刪除。認為某段程式碼該移除時，先標註 // TODO: 建議移除 - 原因：xxx，拿到許可再刪。

配套規範 · 錯誤處理

禁止空 catch。所有 try/catch 和錯誤分支必須有實質性處理：日誌記錄 + 用戶可見的錯誤提示，或合理的降級邏輯。僅 console.log(e)、pass、// ignore 都屬於靜默吞錯，一律不允許。

本節要點

註釋的使命是留存程式碼無法表達的決策信息。三要素結構讓 AI 寫得出來，保護規則讓它刪不掉，兩者配合才能跨越時間。

素材來源：本節內容整理自開源倉庫 itshen/xs_vibe_rules 的 rule-opensource.mdc 第七章「程式碼組織與規範」。