代碼品質是可以衡量的。這句話聽起來顯而易見，但當你試著回答技術長在收購軟體產品前或技術主管在啟動重構專案前提出的問題時，你會發現並非如此：如何判斷程式碼品質好壞？ 「它能用」不是答案。 「團隊審查過了」也不是答案。答案需要持續應用客觀的衡量指標：每個函數的圈複雜度、每個模組的可維護性指數、每千行程式碼的缺陷密度、每個元件的測試覆蓋率、每個迭代週期內每個檔案的程式碼變更率。這些都是數值。我們可以分析數值趨勢、進行基準測試，並據此採取行動。
挑戰在於，程式碼品質指標並非可以互換，也並非具有普遍的解釋性。 COBOL 程式中較高的可維護性指數與 Python 腳本中相同的分數意義截然不同。在經過充分測試的狀態機中，15 的圈複雜度是可以接受的，但在驗證函數中則是一個嚴重的問題。每千行程式碼 (KLOC) 2 個缺陷的缺陷密度在系統程式設計中是優秀的，但在安全關鍵型嵌入式應用程式中則令人擔憂。要使指標真正發揮作用，就需要理解每個指標衡量的是什麼，哪些因素會影響其數值的增減，以及哪些閾值適合特定情境。本文的其餘部分將著重闡述這些內容。
什麼是代碼品質？
程式碼品質是指原始程式碼滿足一系列可衡量屬性的程度，這些屬性使其正確、可維護、可讀、高效、安全且可測試。任何單一屬性都不能孤立地定義品質。運行正確但不可讀的程式碼，每次更改都會降低其質量，因為無法理解它的開發人員無法安全地對其進行修改。可讀但未經測試的程式碼有隱藏缺陷。經過測試但結構複雜的程式碼，隨著其成長會累積更多缺陷，因為複雜性會增加任何給定更改導致意外破壞的機率。
ISO/IEC 25010 標準正式定義了八項軟體品質特性：功能適用性、效能效率、相容性、可用性、可靠性、安全性、可維護性和可移植性。具體到原始程式碼而言，可以直接從程式碼本身（而非運行時行為）衡量的特性包括：可維護性、可靠性（可透過缺陷和複雜度指標近似衡量）、安全性（透過靜態分析）和功能適用性（透過測試覆蓋率）。其他特性則需要執行程式碼才能進行測量。因此，程式碼品質指標僅涵蓋軟體品質中一個已定義且重要的子集，而非全部。
為什麼程式碼品質如此重要
技術團隊深知程式碼品質的重要性。對於業務利害關係人和需要向內部團隊論證程式碼品質價值的團隊而言，成本和時間是關鍵所在。麥肯錫和IT軟體品質聯盟（CISQ）的研究一致表明，開發人員花費30%到40%的時間來處理現有技術債務，而不是開發新功能。低劣的程式碼品質是技術債累積的根源：每個未能及早發現的缺陷、每個過於複雜的功能、每個需要單獨維護的重複邏輯區塊都會增加下一次變更的成本。高品質的程式碼能夠持續降低這些成本，並在系統的整個生命週期中不斷累積。
程式碼品質指標：完整參考
以下指標涵蓋了程式碼品質評估的各個主要類別。對於每個指標，我們都解釋了其定義、測量方法、可接受範圍和解釋。下表中的閾值反映了廣泛引用的行業基準；在安全關鍵型或受監管的環境中，團隊應採用更嚴格的閾值。
複雜性指標
圈複雜度 複雜度度量用於衡量函數或方法中線性無關路徑的數量。它是由托馬斯·麥凱佈於 1976 年提出，至今仍是應用最廣泛的複雜度度量指標。此公式計算決策點， if, else if, switch 案例、循環條件、 catch 程式碼區塊、條件運算符，以及加 1。沒有分支的函數的圈複雜度為 1。
| 圈複雜度 | 同步口譯 |
|---|---|
| 1-5 | 簡單易測 |
| 6-10 | 適中，易於管理 |
| 11-20 | 複雜，測試變得困難 |
| 21-50 | 風險極高，建議重構 |
| 50+ | 無法測試，幾乎可以肯定含有缺陷 |
環路複雜度越高，缺陷密度也越高。發表在 IEEE 軟體工程彙刊上的研究發現，環路複雜度高於 10 的函數，其缺陷率明顯高於環路複雜度較低的函數。 圈複雜度分析 在遺留程式碼庫中，令人擔憂的是，有些函數經過多年的維護，累積了決策邏輯，但從未有人重構過整體結構。
N路徑複雜度 NPath 複雜度統計函數中唯一執行路徑的數量，包括由巢狀條件和循環建立的路徑。圈複雜度線性地計算分支數，而 NPath 複雜度則將其乘以 1：一個包含三個連續 if-else 語句塊的函數，其圈複雜度為 4，但 NPath 複雜度為 8，因為每個條件都可以獨立地為真或假。 NPath 複雜度隨巢狀層數呈指數級成長。 NPath 值超過 200 表示該函數所需的測試案例數量遠遠超過任何團隊實際能夠編寫的數量。
認知複雜性 SonarSource 引入了該指標，它衡量的是程式碼的理解難度，而不是程式碼包含的路徑數。它對嵌套的懲罰比線性分支更重： if 裡面 while 在另一個里面 if 得分高於連續三分。 if 具有相同圈複雜度的語句。認知複雜度更能反映開發人員在閱讀程式碼時實際遇到的困難。通常，認知複雜度高於 15 的方法會被標記為需要審查；高於 25 則表示大多數開發人員會發現該函數確實難以理解。
霍斯特德指標 從原始程式碼中的四個計數中導出一系列度量：不同的運算子數量 (n1)、不同的操作數數量 (n2)、運算符總數 (N1) 和操作數總數 (N2)。 Halstead 是基於這些度量計算：
- 體積 (N × log2(n))：資訊內容實現的規模
- 困難 (n1/2 × N2/n2)：對程式碼編寫或理解難度的估計
- 功夫 （數量 × 難度）：實施或理解程式碼所需的估計總腦力勞動量
Halstead 度量在比較具有相似圈複雜度的函數時特別有用，可以確定哪個函數更難理解。一個包含 10 個分支且變數命名清晰的函數，其 Halstead 難度低於一個包含 10 個分支且變數由計算索引和單字元標識符構成的函數。
可維護性指標
可維護性指標 Halstead 是 Paul Oman 和 Jack Hagemeister 最初開發的綜合指標，後來被 Microsoft Visual Studio 採納為標準可維護性指標。它將 Halstead 體積、圈複雜度和代碼行數結合成一個單一的分數。
Visual Studio 公式會產生一個介於 0 到 100 之間的分數：
| 可維護性指標 | 評分 |
|---|---|
| 20-100 | 永續（綠色） |
| 10-19 | 中等維護需求（黃色） |
| 0-9 | 難以維護（紅色） |
可維護性指數是一個總計統計量。它最適用於識別異常值，即得分處於紅色區域的檔案或模組，而不是對綠色區域內的模組進行細微比較。在 Python 中， radon 該庫直接計算可維護性指數。在 Visual Studio 中，它會顯示在「程式碼指標」視窗中。 靜態程式碼分析 對於平台而言，可維護性指數通常是與圈複雜度和程式碼行數一起作為標準輸出之一。
程式碼行數 (LOC) 和千行數 (KLOC) 用行數或千行數來衡量程式碼庫的大小。單憑行數本身並不能說明程式碼質量，但它為其他指標提供了必要的分母：缺陷密度是指每千行程式碼的缺陷數，註解密度是指每行程式碼的註解數，測試密度是指每行程式碼的測試斷言數。行數也能反映複雜度的成本：一個 500 行、圈複雜度為 20 的函數比一個 50 行、圈複雜度相同的函數要複雜得多。
程式碼流失 程式碼變更率是指程式碼隨時間變化的速率，以單位時間內每個檔案新增行數、刪除行數和修改行數總和來衡量。程式碼變更率高表示系統不穩定：頻繁變更的程式碼可能源自於最初設計有缺陷、需求不穩定或需要不斷修補的漏洞。微軟的研究發現，程式碼變更率最高的 10% 的檔案缺陷數量是變更率低的檔案的五倍。透過追蹤程式碼變更率和缺陷率，可以了解頻繁的變更究竟是在提升程式碼品質，還是在製造新的問題。
程式碼覆蓋率指標
單元測試覆蓋率 程式碼庫中被單元測試執行的程式碼行、分支或條件所佔的百分比。最有意義的形式是分支覆蓋率：程式碼中的每個決策是否都能被至少一個測試在真假兩種結果下執行到。行覆蓋率更容易被操縱，一個不進行任何斷言就執行每一行的測試就能達到 100% 的行覆蓋率，但實際上什麼都沒捕獲到。
單元測試覆蓋率的產業基準：
- 低於 50%：不合格，大多數缺陷無法透過測試發現。
- 50-75%：中等覆蓋率，主要路徑已覆蓋，但可能遺漏了極端情況。
- 75-90%：適用於大多數應用程式程式碼
- 90%以上：適用於安全關鍵型或高可靠性系統
安全關鍵型應用程式中的程式碼覆蓋率 遵循更嚴格的標準。航空軟體的 DO-178C 和功能安全的 IEC 61508 都規定了超出標準單元測試範圍的覆蓋率要求（最高關鍵等級需要條件/決策覆蓋率）。提高安全關鍵型應用的程式碼品質需要能夠追蹤條件/決策覆蓋率並產生認證機構所需正式證據的覆蓋率工具。
測試密度 它透過衡量測試斷言的數量相對於生產程式碼規模的比例來補充程式碼覆蓋率。高覆蓋率但低測試密度可能表示測試執行了程式碼，但並未真正驗證其行為。高測試密度但低覆蓋率則表示測試集中在程式碼庫的一小部分。
缺陷指標
蟲子密度 缺陷密度（也稱為缺陷率）是指每千行程式碼（KLOC）中已確認的缺陷數量。它是衡量程式碼正確性的最直接的定量指標。 CISQ 的行業基準數據顯示，商用現成軟體在測試前平均每千行程式碼約有 15-50 個缺陷；經過測試和發布後，高品質的商用軟體通常每千行程式碼的缺陷數低於 1 個。
靜態分析結果 在測試或生產使用確認缺陷之前，可以估算出缺陷密度。諸如 SonarQube、Checkmarx 等工具以及 SMART TS XL 分析程式碼庫，找出與已知缺陷和漏洞類別相關的模式，並統計潛在問題的數量，以嚴重程度進行分類。關鍵問題和阻塞性問題的數量與程式碼行數 (LOC) 的比率，可以在程式碼進入測試階段之前，提供程式碼品質的早期訊號。
程式碼異味密度 程式碼異味密度是指每千行程式碼（KLOC）中反模式、重複程式碼、過長函數、過度類別耦合、特性偏好、上帝物件等的存在程度。程式碼異味不會立即導致故障，但會預示著未來的缺陷和維護成本。程式碼庫中程式碼異味密度高意味著每次未來變更的成本都會增加，因為每次變更都必須克服累積的結構性問題。
可讀性和風格指標
評論密度 註解行數與程式碼行數的比例。最佳範圍因程式語言和團隊慣例而異，但通常在 10% 到 30% 之間。低於 10% 可能表示程式碼文件不足；高於 50% 可能表示程式碼過於複雜，需要對不明顯的邏輯進行大量解釋。註解的品質比數量更重要：一條能夠重述程式碼功能的註解（// increment i by 1）沒有任何意義，而解釋為什麼選擇特定演算法的評論則具有重要價值。
命名規則合規性 衡量符合項目命名規範的識別符（變數、函數、類別）的百分比。自動化工具可以在程式碼檢查配置中強制執行命名規範。一致的命名是提升程式碼可讀性最有效的方法之一，因為它允許開發人員僅憑識別碼的名稱就能預測其用途，從而降低閱讀不熟悉程式碼的認知負荷。
程式碼重複率 重複程式碼率衡量的是程式碼庫中跨多個位置重複程式碼的百分比。通常情況下，超過 5% 的重複程式碼會被標記出來。重複程式碼會倍增維護工作量：重複邏輯中的錯誤必須在每個副本中尋找並修復，行為變更也必須在所有副本中保持一致。此外，重複程式碼還會掩蓋程式碼庫的真實規模：一個看似有 100,000 萬行程式碼的系統，可能包含 40,000 萬行獨特的邏輯程式碼和 60,000 萬行重複程式碼。
安全和技術債指標
技術債比 SonarQube 將技術負債比率定義為程式碼庫修復成本與開發成本的比值。低於 5% 的技術債務比率被認為是乾淨的程式碼庫；高於 20% 則表示累積了大量債務，這將顯著減緩未來的開發速度。
安全熱點密度 此指標統計每千行程式碼 (KLOC) 中的安全熱點數量，即需要進行安全審查的程式碼模式（而非已確認的漏洞）。例如，未參數化的 SQL 查詢、使用已棄用的加密函數以及未經驗證的輸入處理等。靜態分析工具會識別這些模式，並將其呈現為需要人工安全審查的項目。
漏洞密度 此指標統計每千行程式碼 (KLOC) 中已確認的安全漏洞數量，通常按 CVSS 嚴重性進行分類。此指標在發布後安全審計或持續性安全監控流程中最具意義。
如何衡量程式碼品質：一種實用方法
程式碼品質評估並非單一步驟，而是貫穿開發工作流程的持續性實踐。對於從未經評估的程式碼庫開始的團隊來說，務實的四階段方法非常有效。
第一階段：建立基線。 在進行任何更改之前，請對程式碼庫進行完整的靜態分析。記錄目前程式碼的圈複雜度分佈、檔案可維護性指數、缺陷密度、程式碼覆蓋率和重複率。此基線是所有後續測量結果的基準。如果沒有基線，就無法判斷變更是提高了程式碼品質還是降低了程式碼品質。
第二階段：確定閾值。 根據具體情況，為每個指標設定可接受的閾值。例如，商業網路應用和安全關鍵型醫療設備的閾值就有所不同。將這些閾值記錄在專案品質標準中，並讓整個團隊都能看到。
第三階段：整合到 CI/CD 中。 配置持續整合 (CI) 管線，使其在每次提交或拉取請求時計算關鍵指標。標記任何超出可接受範圍的指標變更。阻止引入圈複雜度高於閾值的新程式碼、降低程式碼覆蓋率至閾值以下或引入嚴重靜態分析結果的合併操作。這使得指標閾值從指導原則轉變為強制執行的標準。
第四階段：回顧趨勢，而非快照。 單一指標讀數只能提供資訊；趨勢才能指導行動。特定模組的程式碼變更率呈上升趨勢、整個發布週期內的程式碼覆蓋率呈下降趨勢，或特定檔案的可維護性指數呈下降趨勢，這些都表明存在一些問題，而快照式測量可能忽略這些問題。在每次迭代回顧會議上都要審查這些指標趨勢。
企業級、敏捷開發與安全關鍵型環境下的程式碼品質指標
敏捷開發中的程式碼品質指標
敏捷團隊在程式碼品質指標方面面臨著一個特殊的挑戰：強調在短週期內交付可用的軟體，可能會導致在品質問題尚未解決之前就匆忙發布。解決方案並非放棄指標，而是將其納入「完成定義」中。一個使用者故事並非在功能實現時就已完成；而是在功能實現且新程式碼達到團隊品質標準時才算完成。
在敏捷開發環境中，領先指標（即預測未來問題的指標）包括程式碼變更率、每次迭代引入的新技術債務以及每次發布中靜態分析發現的問題數量趨勢。滯後指標（即衡量已產生結果的指標）包括測試中發現的缺陷密度、維護時間與新功能開發時間的比值以及每次發布的生產事故率。
技術盡職調查中的程式碼品質
在併購交易、供應商選擇和系統購置過程中，技術盡職調查需要對整個程式碼庫的程式碼品質進行結構化評估。在此背景下，最重要的指標包括：
- 可維護性指數分佈程式庫中分別有多少百分比落在紅色、黃色和綠色區域？
- 技術債比相對於開發成本，預計修復成本為何？
- 缺陷密度每千行程式碼 (KLOC) 中存在多少已知缺陷？與行業基準相比如何？
- 測試覆蓋率自動化測試涵蓋了程式碼庫的百分之多少，以及涵蓋的等級（行、分支、條件）是什麼？
- 依賴性健康：存在多少外部依賴項，其中有多少已經過時或被棄用，以及架構的耦合程度如何？
- 程式碼重複程式碼庫中重複程式碼的比例，顯示了維護風險。
從以下角度進行考察： 企業程式碼評估的影響分析了解每個組件在品質指標上的得分，以及組件之間的相互依賴關係，對於準確的盡職調查至關重要：一個孤立的低品質模組可能代表可控的修復成本，而位於密集依賴關係圖中心的同一模組則代表著更大的風險。
安全關鍵型和金融科技應用中的程式碼質量
航空、汽車、醫療設備和工業控制等領域的安全關鍵型應用，其程式碼品質標準遠高於一般商業軟體。主要區別如下：
- 圈複雜度限制通常設定為 10 或更低，例外情況需要正式的理由。
- 承保範圍要求採用 MC/DC（修改後的條件/決定承保範圍），而非線路或分支承保範圍。
- 靜態分析必須使用經過認證的工具進行，違規行為必須記錄在案並予以解決或正式接受。
- 程式碼變更率被視為一項安全指標：安全關鍵模組的高變更率會觸發額外的審查和重新驗證。
金融科技應用也面臨來自監管框架的類似壓力。 PCI DSS 要求採用安全的編碼標準和代碼審查流程。財務報告系統的 SOX 合規性要求從需求到程式碼再到測試的可追溯性。程式碼品質指標提供了這些流程有效運作的客觀證據：覆蓋率報告證明測試存在，靜態分析報告證明已檢查已知的漏洞模式，複雜度報告則表明審查人員能夠合理地評估程式碼。
按語言劃分的程式碼品質指標
Python程式碼品質指標 可以使用以下方式計算 radon （圈複雜度和可維護性指數）， pylint （代碼異味和風格違規） coverage.py （測試覆蓋率）， bandit （安全問題），以及 mypy or pyright （類型正確性）。可維護性指數 radon 使用針對 Python 校準的改進版 Halstead 公式。 A 級為 20 以上，B 級為 10-20，C 級為 10 以下。
角色扮演遊戲代碼品質 在 IBM i 上需要專門的工具，因為標準品質指標工具無法解析 RPG 語法。 SMART TS XL 它為 RPG 程式提供圈複雜度、程式碼行數和依賴性分析，這對於管理大型遺留程式碼庫的 IBM i 使用者來說尤其有價值，因為以前無法實現品質測量的自動化。
程式碼審查指標
程式碼審查是一種品質控制活動，其本身的有效性是可以衡量的：
- 審查範圍：已提交代碼中在合併前經過正式審查的百分比
- 審查中發現的缺陷：審查過程中發現的缺陷數量相對於已審查變更集的大小。
- 審核週轉時間從發起拉取請求到審核合併所需的時間
- 評論解決率：導致程式碼修改的評論百分比，與被忽略的評論百分比。
高效團隊通常程式碼審查覆蓋率超過 90%，平均每次審查發現的缺陷數量在每百行程式碼 1-3 個之間，且週轉時間短。審查指標有助於判斷程式碼審查是真正發揮了品質把關的作用，還是僅僅流於形式。
持續代碼品質監控
一次性的程式碼品質測量遠不如持續監控有價值。程式碼品質並非程式碼庫的固定屬性，它會隨著每次提交而變化。如果品質指標沒有持續跟踪，即使今天看起來品質良好，經過三個迭代周期的倉促開發，程式碼庫的品質也可能顯著下降。
有效的持續程式碼品質監控包括：
- 每次提交指標計算：每次推送計算的圈複雜度與靜態分析結果
- 趨勢儀錶板：以視覺化方式展示關鍵指標隨時間的變化，每日或按版本更新
- CI/CD 中的質量門自動強制執行影響可維護性、安全性和缺陷風險的指標的最低閾值
- 迴歸檢測：當某個指標在版本發布之間出現顯著的負面變化時發出警報
程式碼品質改進的領先指標，也就是預測下一版本品質是提升還是下降的訊號，包括程式碼覆蓋率趨勢、每個迭代周期引入的新複雜度以及已解決程式碼異味與新增程式碼異味的比率。當這些指標朝著正確的方向發展時，程式碼品質就會提升。反之，在品質惡化完全發生之前，我們就能預見它的下降趨勢。
SMART TS XL 衡量並提高程式碼品質
SMART TS XL 它能夠計算本文所述的全部程式碼品質指標，並支援開發環境中所有語言和平台：COBOL、JCL、Java、.NET、Python、JavaScript、TypeScript、RPG、SQL 等。大多數品質工具一次只能處理一種語言， SMART TS XL 建立整個系統的統一品質模型，從而可以跨語言比較質量，在系統層級而不是文件層級追蹤指標，並識別單語言工具無法看到的跨組件品質問題。
對於擁有大型、多語言程式碼庫的企業組織而言， 靜態程式碼分析 的能力 SMART TS XL 它提供了技術盡職調查、傳統系統現代化規劃和持續品質改進所需的基準測量數據。 依賴映射 能力將品質評估擴展到結構性問題：哪些元件依賴性最強，哪些變更的影響範圍最大，以及當品質指標與依賴中心性結合時，程式碼庫的哪些區域代表著最高的維護風險。
SMART TS XL的程式碼品質指標透過其 API 與 DevOps 流水線集成，從而在 CI/CD 層實現品質門控。當提交引入的函數圈複雜度超過閾值、程式碼覆蓋率低於配置的最低值，或引入關鍵的靜態分析結果時，管線會發出特定的診斷信息，告知開發人員具體的測量結果以及未達到閾值的原因，從而導致建置失敗。這使得品質控制從發布後審核轉移到開發過程中的回饋，透過在問題修復成本最低的時候發現並解決它們，降低了品質問題的成本。
程式碼品質是一種團隊紀律，而非一份報告。
程式碼品質指標的價值完全取決於團隊如何利用它們。一份無人問津的季度程式碼品質報告比沒有報告更糟糕，因為它會造成一種品質管理良好的假象，而實際上程式碼庫卻在無人監管的情況下不斷惡化。只有當指標能夠驅動具體的行動時，它們才真正具有價值：例如，當新函數的圈複雜度激增時，會在合併該函數之前發起重構討論；當模組的覆蓋率下降時，會發起測試迭代；當特定組件的缺陷密度上升時，會發起對該組件設計的正式審查。
建構這種文化需要在開發過程中（而非發布之後）適時地將指標視覺化，並將其與團隊的具體承諾聯繫起來。那些在每次迭代回顧會議上審查程式碼品質趨勢、將品質閾值納入「完成」定義、並將指標回歸與功能回歸同等重視的團隊，建構的程式碼庫維護成本更低，隨著時間的推移，生產事故也更少。衡量是起點，而紀律才是產生結果的關鍵。
