程式碼重構風格一致性：五條可驗證的規則

程式碼重構常被誤解成「把程式寫得比較漂亮」，於是格式、命名、模組拆分與行為修改被混在同一個大變更裡。結果是 reviewer 難以判斷真正改了什麼，測試失敗時也很難定位原因。風格一致性的價值不是讓每一行長得一樣，而是讓團隊能更快讀懂差異、降低維護成本，並把注意力放在真正的設計與行為風險。

這篇保留原本「一致風格規則」的核心，但不做過時的年度預測。以下五條規則可作為重構前、重構中與程式碼審查時的共同檢查點；它們不是所有語言都必須照抄的規範，而是用來把風格決策、行為驗證與團隊溝通分開處理。

先釐清：風格一致不等於所有地方都強制重寫

一致性要先有範圍。專案通常同時存在語言官方慣例、團隊規範、既有模組的局部慣例與自動化工具設定。若每次碰到舊檔都順手全檔重排，會造成大量 diff noise，也讓真正的行為修改被淹沒。

Google 的公開風格指南把一致性列為可讀性的要素，也指出當規則沒有涵蓋某個細節時，應尊重接近程式碼的既有一致做法。這不表示舊寫法永遠不能改，而是要讓重構範圍、理由與驗收方式清楚可見。

五條可驗證的一致風格規則

1. 讓格式規則有單一來源

縮排、引號、換行、import 排序與 lint 規則應由專案設定檔與可重複執行的工具決定，而不是靠 reviewer 每次記憶。formatter 與 linter 能把可機械化的討論移到 CI 或本機指令，讓 review 回到命名、邊界、可讀性與行為。

自動格式化也有邊界。以 Prettier 為例，它把「輸出有效程式且不改變原有行為」視為格式化的正確性目標；格式工具並不會替你重新設計 API、修正邏輯或判斷商業規則。

2. 把純格式調整與行為重構拆開

一次變更若同時包含全檔重排、改名、抽取函式與功能修改，審查者很難分辨哪些差異可能影響使用者。較容易驗證的做法是先提交純格式化變更，再以小而完整的後續變更處理重構或功能。Google 的 code review 指南也明確建議，重大風格調整不要和其他變更混在一起。

如果專案確實需要大規模格式遷移，請把它當成獨立工作：固定 formatter 版本、避免在中途變更設定、記錄影響範圍，並在完成後再開始功能性工作。

3. 優先維持模組內的局部一致性

同一個檔案或套件裡，名稱、錯誤處理、資料驗證、非同步流程與測試命名應採用同一種易讀模式。重構時不要只把新程式碼改成「你喜歡的樣子」，卻留下相鄰區塊採用另一套慣例。先閱讀周邊程式，辨認真正需要統一的範圍，再用小變更逐步收斂。

若局部慣例本身與明確的專案規範衝突，應建立追蹤事項或安排獨立清理，而不是在一個無關的修補中悄悄擴大範圍。

4. 把「行為不變」變成可檢查的前提

重構的經典定義是調整內部結構而不改變可觀察行為。這表示開始前就要知道什麼行為必須保留：公開 API、輸入驗證、錯誤型別、資料格式、併發語意、效能門檻或使用者可見的畫面流程。既有測試不足時，先補上最能描述現況的測試，再動結構。

不要因為 formatter、型別檢查或單元測試通過，就推論整個重構安全。依變更範圍選擇單元、整合、端對端、效能或人工驗收；對付款、權限、資料刪除、醫療與其他高影響流程，更不能把自動工具結果當成唯一放行條件。

5. 以小而完整的變更建立可審查性

小變更不是把一個功能切成無法理解的碎片，而是每次只處理一個可說明、可測試、可回復的目標。Google 的 code review 指南將小型、完整的變更視為更容易審查、推理與回退的做法。對重構而言，這通常意味著一次先抽出一個函式、統一一組錯誤處理或搬移一個清楚的邊界，而不是同時重寫整個模組。

一個安全的重構順序

界定目標：寫下這次要改善的可讀性或維護痛點，以及不應改變的外部行為。
建立基線：確認測試、型別檢查、lint 與必要的手動驗收目前可用；若舊程式沒有保護，先補最小的行為描述測試。
先處理機械性變更：若需要格式化，獨立提交並固定工具版本與設定。
進行一項結構調整：維持 diff 聚焦，例如抽取函式、縮小一個責任範圍或統一命名，而不是同時改功能。
重新驗證與審查：檢查測試、關鍵使用情境、文件與觀測訊號；讓 reviewer 知道這次變更想保留什麼行為、改進什麼結構。

把規則放進工具，也放進溝通

一致風格需要兩個層次。第一層是可自動執行的設定，例如 formatter、linter、型別檢查、測試與 pre-commit／CI。第二層是人類判斷：命名是否表達意圖、抽象是否過度、註解是否解釋原因、介面是否容易誤用。後者無法靠單一工具完全取代，因此 PR 描述和 review 仍應交代重構動機、驗證範圍與已知限制。

審查時可以依序問：這是純格式調整還是行為改動？規則來源是否清楚？相鄰程式是否更一致？測試是否覆蓋受影響的可觀察行為？若答案不明確，就先縮小變更或補上必要資訊，而不是用個人風格偏好阻擋整個工作。