跳轉到

08.2 veryl fmt 格式化#

靜態檢查抓的是錯誤，格式化處理的是風格。聽起來小事，但風格之爭消耗的工程時間可能比想像中大得多。veryl fmt 把格式問題從團隊討論中永久移除。

veryl fmt 做什麼#

veryl fmt 內建於 Veryl 工具鏈，對 .veryl 檔案執行自動格式化：縮排、對齊、空白、斷行位置等都由工具統一決定。使用者沒有風格選項可以調（或極少），這是刻意的設計：格式只有一種正確寫法，就是工具輸出的那種。

veryl fmt

搭配 veryl fmt --check 可以只驗證不改寫——這是 CI 中常用的形式：若有人提交了未格式化的程式碼，check 會失敗並擋下。

gofmt 與 rustfmt：「格式不是戰場」的文化#

Veryl 的做法直接繼承自軟體界兩個先例。

2012 年，Go 語言發布了 gofmt，作為語言發行版的一部分。gofmt 幾乎不提供任何格式選項，整個 Go 社群的程式碼因此長得一模一樣。這個決定的深遠影響被後人總結為一句話：「gofmt 的風格沒有人都喜歡，但沒有人再吵格式了。」格式從個人偏好變成非議題，code review 的注意力回歸到邏輯與設計。

Rust 隨後以 rustfmt 沿襲了同樣路線：官方格式、社群一致、CI 強制。兩者的共同哲學是：格式的價值不在「美」，而在「一致」——一致降低閱讀成本，而程式碼被閱讀的次數遠多於被撰寫。

對照：SV 時代的 code style 文件滿天飛#

在 SystemVerilog 世界，同樣的問題是用完全不同的方式解決的：人寫的風格準則。

大公司的設計部門幾乎都有一份數十頁的 coding style guideline：縮排用幾格、訊號命名前綴、begin/end 該不該換行、位寬怎麼標……這些文件由資深工程師制定、新人入職時發放、code review 時人工執法。配合這些準則的還有商業 lint 工具中的一大類「風格規則」，用設定檔逼近公司準則。

這個制度的成本顯而易見：

  • 文件本身需要撰寫、維護、裁決爭議，準則委員會是許多大公司真實存在的組織。
  • 執行靠人：review 中大量篇幅在糾正縮排與命名，擠壓了對設計本身的討論。
  • 工具與文件的設定漂移：lint 設定更新了，文件沒跟上，新人無所適從。

自動格式化把這整套制度壓縮成一個工具、零討論。

fmt 對 code review 噪音的削減#

格式自動化對團隊協作的實際影響，可以用 review 噪音來衡量。沒有 fmt 的專案中，一個 pull request 的 diff 常常混雜著「純格式變更」與「邏輯變更」：同一行被改，可能只是縮排調整。reviewer 必須逐行分辨哪些變更有語意、哪些沒有，這是純粹的浪費。

有了 veryl fmt，這個問題在結構上消失：

  • 所有提交進 repo 的程式碼格式一致，diff 中不會出現格式噪音。
  • reviewer 的注意力全部留給介面、時序、位寬這些真正重要的判斷。
  • 新人不需要先學會公司的風格才能提交程式碼，工具就是風格。

小結#

veryl fmt 繼承 gofmt 與 rustfmt 開創的「格式不是戰場」文化，把 SV 時代靠數十頁準則文件與人工執法維持的程式碼一致性，換成一條命令與一行 CI 設定。它與 veryl check 一起構成品質管線的兩根柱子：check 管正確性，fmt 管一致性。下一章看管線的第三根柱子——文件。