代碼質量規范(草稿)
目前本規范狀態為草稿, 需要進一步修改謬誤, 并進行優化和補充. 歡迎讀到這個規范的朋友能夠提出寶貴意見, 一同改進!
參考資料如下:
- Build Maintainable software by Joost Visser (O'Reilly Media)
- SIG 軟件質量評估標準
1 針對代碼單元的質量要求
(這些內容可以利用靜態檢查工具進行檢查)
- 應編寫短小的代碼單元: 將代碼單元(方法或構造函數)的長度限制在15行內. 若不滿足, 則將方法展開處理, 或是將方法封裝為方法對象.
- 應編寫簡單的代碼單元: 將代碼單元的環路復雜度最大限制在 5(分支結點數加 1). 這個是在許多工程中都得到驗證的一個合理的值, 最大上限不超過 10. 若不滿足, 則采用多態替換或字典對照的解決辦法.
- 應編寫簡單的代碼單元接口: 將代碼單元的參數個數限制在 4 個內, 如果超過這個限制, 則對方法進行展開處理, 或者是封裝參數對象進行處理.
- 嚴格禁止使用復制粘貼代碼: 禁止在同一工程中直接復制粘貼代碼, 禁止從其他工程中復制代碼到當前工程. 復制粘貼導致的問題比復雜的代碼更大, 一處寫出的 bug 就是這樣被帶到多個地方.(同一工程中簡單的復制粘貼可以通過 CPD 工具檢測).
- 標識符或類型名的最小長度應限制在 2 個以上, 并應避免過長的標識符, 但命名時應先保證命名的易讀, 然后再保證長度不過長.
- 一個代碼單元的職責應是單一的, 即一個代碼單元只做一件事情.
2 針對模塊級及其以上的代碼質量要求
(如下只有部分內容可以利用靜態檢測工具檢測, 更多是自己在開發過程中時刻去關注).
- 保證模塊的單一關注點, 減少單一模塊的代碼數量(這個可以通過靜態檢查工具進行檢查, 經驗值是模塊代碼量控制在 300 行內).
- 應利用接口隱藏實現, 降低模塊間耦合度.
- 應將模塊封裝為 Framework 或 Library, 再引入使用, 保證主工程的 Code Base 體積小.
- 應保證作為組件接口的模塊體積盡可能小, 并且作為接口的模塊應避免調用其他組件接口模塊, 降低耦合. 實踐中常用的做法是使用抽象工廠作為組件接口.
- 應從更高的抽象層級上定義組件接口.
- 保證系統中頂層組件的數量合理, 且各個組件的體積接近, 經驗值是控制在 6 到 12 個之間. 實踐中應更多關注系統功能的劃分是否合理, 若是一個合理的系統, 其頂層組件數量和組件體積都能夠很好符合這條規則的要求.
- 應保證單一代碼庫的體積盡可能小. 可行的做法有: 1)防止代碼庫中出現復制粘貼代碼. 2)相同功能前提下的代碼實現應簡單小巧. 3)利用 Framework 或 library 引入三方功能. 4)將大系統分解為若干獨立的小系統.
3 對于代碼測試的要求
- 應編寫完整的代碼單元測試, 單元測試應保證至少 80% 的覆蓋率.
- 應針對模塊功能, 編寫相應的集成測試.
- 應針對系統功能, 實現相應的端對端測試.
- 應進行自動化測試, 可利用相應平臺的測試 Framework 編寫測試.
- 應保證測試實現代碼的質量符合本規范第一第二及第四節質量要求.
4 其他要求
- 在代碼中不應保留 Dead Code: 1)應清理不再被調用的代碼. 2)應清理其結果不再被使用的代碼. 3)應清理被注釋掉的代碼. 4)應清理永遠不會被執行到的代碼單元組成部分.
- 在代碼中不應出現魔法數字. 遇到魔法數字的情況下應替換為常量進行表示.
- 應對代碼中的異常進行正確處理: 1)應保證代碼中的異常都能被捕捉. 2)應盡可能按特定異常類型進行捕捉. 3)應根據要求對異常進行合理處理, 若顯示給最終用戶, 需要以用戶友好的形式呈現.
- 應根據優先級和著眼點將本規范合理應用到實際軟件工程施工中. 其中代碼單元質量要求應優先于模塊或組件進行落實.
