We can never see past the choices we don’t understand. – Oracle (The Matrix)

副標(biāo)題是：“一個使用 code-maat, git, Python, D3.js 進行代碼質(zhì)量衡量的 case study“。

大概是在2017年6月份吧，我當(dāng)時在工作中作為一些小項目的負(fù)責(zé)人，收到了同事的一份報表，主要內(nèi)容是通過 jsinspect ，檢測出了有幾個項目代碼重復(fù)率比較高，提醒我是否有些項目需要優(yōu)化或部分重構(gòu)一下。我當(dāng)時第一次萌生了作為周期性項目，代碼的質(zhì)量是應(yīng)該作為一個指標(biāo)隨著迭代被量化，從而指導(dǎo)后續(xù)項目迭代的，雖然當(dāng)時我聽說過 sonar。隨后我工作中參與了一個中心化代碼質(zhì)量評估系統(tǒng)一期的設(shè)計和開發(fā)(主要是針對 javascript 代碼的規(guī)范和質(zhì)量檢測與持續(xù)集成進行耦合)，但是當(dāng)時這個系統(tǒng)沒有解決這樣一個問題，即能夠告訴我代碼里具體哪部分存在更高優(yōu)先級被重構(gòu)的需要。半年過去了，現(xiàn)在我嘗試回答一下這個問題，并舉一個與編程語言無關(guān)的一個通用可行的例子，通過這個例子揭示一個事實：

“代碼的歷史，是代碼未來的預(yù)言“

如果把項目代碼比喻成城市，那么系統(tǒng)中維護成本高的復(fù)雜部分就好比潛伏在城市中的罪犯，我們對于罪犯的搜查，顯然不能對城市進行地毯式的搜索，而是應(yīng)該找到之前有過犯罪記錄的一些街區(qū)，劃分重點區(qū)域進行排查，我們把這些區(qū)域，稱為 hotspot，代碼中也是，這些 hotspot 里，潛藏著具有最高優(yōu)先級的需要調(diào)整，優(yōu)化與被重構(gòu)的對象。

CodeCity 生成的“代碼城市”，每個街區(qū)是一個 package，每個 class 是一個建筑，建筑的高度是 class 中方法的數(shù)量(這個工具是 OOP 語言專用的，比如 java，我們后續(xù)不談?wù)撍?

我們的目的就是確認(rèn)一個項目中的 hotspot 存在在哪兒。首先，我們不把代碼復(fù)雜度作為確認(rèn) hotspot 的唯一維度，代碼復(fù)雜度很有用，但是單一把復(fù)雜度作為 hotspot 衡量的指標(biāo)，會存在一些問題，最主要的問題就是一段復(fù)雜的代碼，只有當(dāng)我們真的需要關(guān)注并修改它的時候，它才是問題所在，如果沒有人需要閱讀或修改這段復(fù)雜的代碼，它具體的復(fù)雜度是多是少又有什么關(guān)系呢?即便有人覺得這種代碼是定時炸彈，但是一個具有一定規(guī)模的系統(tǒng)中存在復(fù)雜模塊是很正常的事情，一次性把這些復(fù)雜模塊都作為 hotspot 標(biāo)注出來并不合理，我們對 hotspot 進行調(diào)整和優(yōu)化也存在風(fēng)險，以合適的策略去優(yōu)化真正需要優(yōu)化的部分是很重要的。

選擇維度

我們使用代碼更改的頻率，作為耗費開發(fā)人員和時間的第一個維度。以 React 為例，我們看下它在 15.0.0(2016 年 4 月 9 日 release)和 16.0.0(2017 年 9 月 27 日 release)之間，都做了哪些修改。為了保證時間的一致性，我們先把項目時間切到 2017 年 9 月 27 日：

git checkout `git rev-list -n 1 --before="2017-09-27" master` 

接下來我們看一下從 2016 年 4 月 9 日到 2017 年 9 月 27 日之間結(jié)構(gòu)化的 git 日志：

git log --pretty=format:'[%h] %an %ad %s' --date=short --numstat --before=2017-09-27 --after=2016-04-09 > react_evo.log 

git 提交日志

在我們自己重定向的 git 的日志文件 react_evo.log 中，我們使用 code-maat 去獲取代碼變動頻率的數(shù)據(jù)，code-maat 使用 Clojure 編寫，用于挖掘和分析版本控制軟件中的項目代碼變動數(shù)據(jù)，我們把他 clone 下來，通過 leiningen 去編譯它的 jar 包執(zhí)行，或者你也可以把它放在系統(tǒng)路徑中做成一個系統(tǒng)命令，我自己也制作了一個 code-maat 的 Docker 鏡像，地址是 code-maat。

我們來試著使用一下 code-maat，先看一下 React 在兩個版本之間的一些匯總數(shù)據(jù)

java -jar code-maat/target/code-maat-1.1-SNAPSHOT-standalone.jar -l react_evo.log -c git -a summary 

匯總情況

可以看到兩個版本之間提交次數(shù)，涉及文件的情況和開發(fā)者人數(shù)的信息。我們再來看一下代碼變動的頻率，并生成一個 csv 文件：

java -jar ../../code-maat/target/code-maat-1.1-SNAPSHOT-standalone.jar -l react_evo.log -c git -a revisions > react_freqs.csv 

文件的修改次數(shù)排序

有了這些數(shù)據(jù)，就縮小了候選 hotspot 的范圍，我們接下來，再增加另外一個判斷模塊規(guī)模的維度，即代碼行數(shù)，代碼行數(shù)這個維度簡單粗暴，并且有兩個好處，其一是能夠查找方便快速;另外就是對于不同編程語言，它是中立的指標(biāo)。我們使用 cloc 作為通過代碼行數(shù)對項目進行分析的工具，它使用 Perl 編寫(誰說 Perl 死了?)，并且能夠得到針對編程語言，文件，空格，注釋和代碼本身的很直觀的輸出，我們在 React 項目中來嘗試一下：

cloc ./ --by-file --csv --quiet --report-file=react_lines.csv 

在反應(yīng)代碼行數(shù)的 react_lines.csv 中，我們能看到一個新的維度：

代碼行數(shù)排序

維度的合并以及可視化

單一維度對于我們來說，不足以說明某個可能存在 hotspot，接下來我們做一下維度的合并，我們把代碼更改的頻率和代碼行數(shù)合并，形成代碼修改次數(shù) + 代碼行數(shù)的一個新的綜合維度，在這個維度中，代碼修改次數(shù)要比代碼行數(shù)擁有更多的權(quán)重。這個工作我們通過 Python 編寫腳本完成，Python 腳本的代碼位于 hotspots-helper。我們來看一下新的維度產(chǎn)生的數(shù)據(jù)：

python merge_comp_freqs.py ../complexity/data/react_freqs.csv ../complexity/data/react_lines.csv > react_hotspot_candidates.csv

代碼修改次數(shù) + 代碼行數(shù)排序

這個維度非常清晰的表達了 React 從 15.0.0 到 16.0.0 的主要代碼改變，來源于 React fiber，fiber 帶來了大量的代碼和多次的修正，其中排名前三的有兩個都是渲染過程中 fiber 用來調(diào)度任務(wù)的部分。排名前幾位的代碼行數(shù)累計近萬，這么多代碼逐個去閱讀源碼還是很消耗精力的，不過通過這些數(shù)據(jù)，我們可以使用 D3.js 做一些可視化，通過 circle packing 算法，得到一個 enclosure diagram，圖中每個圓的直徑越大，代表這個模塊/文件代碼行數(shù)越多，顏色越深代表這個模塊/文件修改的次數(shù)越多，改動越頻繁：

React 代碼從 15.0.0 到 16.0.0 的可視化

hotspots 候選文件

具體可視化頁面參考 Complexity Study，我也做了一個 Docker 鏡像，地址是 youngleehua/complexity-study。

文件命名和再引入的復(fù)雜度分析

現(xiàn)在我們嘗試在這些潛在的 hotspots 中找出真正的問題，我們再增加一個維度，即文件命名。文件，類，函數(shù)的命名，能夠非常好的體現(xiàn)出開發(fā)者的設(shè)計意圖，通常情況下，我們閱讀代碼都是通過文件，類和函數(shù)的命名領(lǐng)會之前開發(fā)者的設(shè)計和思想的。命名不但能夠區(qū)分出哪些是配置文件，哪些是代碼本身，而且也能區(qū)分出文件所負(fù)責(zé)的職責(zé)，好的文件命名，能夠確認(rèn)模塊的代碼職責(zé)，讓代碼內(nèi)聚，盡可能的減少后續(xù)其他職責(zé)代碼的加入，避免邏輯變得過于復(fù)雜，增加修改次數(shù)和bug。例如相比 ReactFiberBeginWork.js，ReactDOMComponent.js 就是一個更好的命名，如果不去看 ReactFiberCommitWork.js 以及 ReactFiberCompleteWork.js 得出 Fiber 自己有個調(diào)度周期的結(jié)論，ReactFiberBeginWork.js 顯得不那么友好和清晰(誰都知道一個模塊需要一個初始的代碼)，而通過文件命名，我們也能明顯的排除一些文件比如 package.json 這種項目的配置文件(不過配置文件產(chǎn)生問題的情況并不是沒有，參考大型C語言項目的Makefile)。

接下來，我們針對命名上并不友好以及在綜合維度上排名靠前的文件做一次代碼復(fù)雜度分析，并根據(jù)復(fù)雜度分析，確定代碼復(fù)雜度在歷史提交中的變化，以及為后續(xù)代碼的修改提供指導(dǎo)和意見。復(fù)雜度分析的手段目前看來也比較多，比如圈復(fù)雜度，也存在針對語言的復(fù)雜度分析工具，例如針對 Javascript 的 es-analysis/plato，但是為了做到語言的中立，形成一個通用的方案，我通過代碼的縮進來標(biāo)志代碼文件的復(fù)雜度情況。

對于大多數(shù)語言來說(尤其對于C-like的語言)，代碼縮進代表的是更深層次的邏輯，邏輯層次越深，需要控制的邏輯也就越復(fù)雜，可能產(chǎn)生的問題也就越多。下面兩個文件，你更希望自己維護哪一個?我更希望自己負(fù)責(zé)維護的是左邊的代碼:)

代碼的形狀

我們還是使用 Python，對代碼的縮進進行分析，我們把一個 tab 和 2 個空格(為了符合 React 代碼的風(fēng)格)作為一個邏輯上的縮進，忽略掉空行，每個縮緊作為一個復(fù)雜度的得分(1 分)，看一看整個文件的總復(fù)雜度，平均復(fù)雜度，復(fù)雜度的方差以及最大復(fù)雜度。

python complexity_analysis.py ./react/src/renderers/shared/fiber/ReactFiberBeginWork.js 

不算空行共 766 行，復(fù)雜度總分 1981，平均分 2.59，方差 1.29，最大得分 8 分

n 代表不計算空行一共的行數(shù)，共 766 行;total 代表文件復(fù)雜度的總分 1981 分，分值很高(如果橫向比對其他文件更明顯);mean 代表平均分表現(xiàn)還好為 2.59 分;sd代表方差得分越低表示有越多的行的復(fù)雜度得分接近平均分，得分 1.29 比較不錯，但是最大的行復(fù)雜度達到了 8 分，算是比較大的數(shù)值了。后續(xù)這個文件的職責(zé)能否被進一步單一化，把更多的邏輯剝離出來呢?這個就需要 React 的開發(fā)者們進行衡量了。

綜合維度排名第一的 ReactFiberScheduler.js 的得分

我們也可以通過版本控制(從最初的 react_evo.log 得到首尾的版本)，得到一個代碼復(fù)雜度的變化信息：

python ../hotspots-helper/git_complexity_trend.py --start 95fed0163 --end 9ce135f86 --file ./src/renderers/shared/fiber/ReactFiberBeginWork.js > complexity_trend.csv 

通過 excel 我們看下 復(fù)雜度的變化趨勢：

ReactFiberBeginWork.js 復(fù)雜度在 15.0.0 版本到 16.0.0 版本之間的變化趨勢

有了這些數(shù)據(jù)以及可視化的體驗，我們不但能夠在不熟悉一個項目的情況下了解代碼的結(jié)構(gòu)，找到可能的 hotspot，也能夠通過版本控制系統(tǒng)，得到具體文件質(zhì)量的趨勢變化，從而能夠指導(dǎo) code review，也能夠為后續(xù)代碼的重構(gòu)指明方向。

結(jié)語

對于軟件質(zhì)量，僅僅分析代碼中的 hotspot 還是不夠的，除了代碼層面隱藏的缺陷，我們這里還沒有分析更宏觀的架構(gòu)上的演進，以及開發(fā)者與代碼之間社會學(xué)層面上的關(guān)系。在這篇之后，我做個預(yù)告，下一篇關(guān)于代碼和工程質(zhì)量分析的文章我將嘗試從更宏觀的角度，闡述如何量化代碼架構(gòu)，通過分析指導(dǎo)一個工程在架構(gòu)上的迭代和重構(gòu)，祝大家 Happy coding in 2018。