寫出有營養的代碼註釋：前置條件、後置條件、序列依賴三大黃金法則

註釋的核心價值

註釋不是寫給編譯器看的，是寫給未來的自己、接手的同事、審核的架構師看的。好註釋記錄的是編碼時的思維決策，而非代碼字面翻譯。

方法級註釋三大必寫項

1. 前置條件 —— 方法開頭標註

「什麼情況下能保證正確運行？」

void sqrt(double x) {
    // pre: x >= 0
    ...
}

• 非所有方法都有前置條件（如加法無前置）
• 有前置條件必須寫，否則調用者會踩坑

2. 後置條件 —— 方法結尾標註

「執行完會造成什麼影響？返回什麼？修改了什麼狀態？」

void setName(String name) {
    ...
    // post: this.name == name && returns void
}

• 所有方法都有後置條件（無副作用的方法也應註明「無副作用」）
• 嚴禁省略

3. 序列依賴 —— 關鍵代碼塊前標註

「這幾行順序不能亂，原因是什麼？」

// 處理訂單結算
// sequence dependent
// 1st: 計算商品總價
// 2nd: 應用優惠券折扣
// 3rd: 計算運費並生成最終金額
calculateTotal();
applyCoupon();
calculateShipping();

• 防止重構時無意打亂邏輯順序
• 空行隔開，視覺醒目

補充規則

• 公式/定理引用：註明出處、關鍵參數、適用邊界（勾股定理等常識除外）
• 時機原則：寫代碼時同步寫註釋，事後補註釋 = 廢話堆砌，不如寫進設計文檔
• 拒絕廢話：// i++ // i 加 1 這類註釋純噪音

一句話總結

註釋要求記錄程式設計師寫程式時的思維過程——前置條件守門、後置條件交代、序列依賴防錯，寫在當下，服務未來。