Code Review 指引

為什麼需要 Code Review

要瞭解為什麼需要 code review 之前，先透過下面這張圖解釋，隨著軟體開發週期越後面的階段或經歷的時間越長，軟體修復 bug 的成本越高。
01
▲圖 1 軟體修復成本與時間關係（資料來源：https://buildsecurityin.us-cert.gov/articles/best-practices/security-testing/risk-based-and-functional-security-testing）
為什麼越晚修復，成本會越高呢？這跟技術債的情況相同，債會生利息，而這利息與循環利息和複利一樣可怕。開發越後期大樓越蓋越歪，疊床架屋與貪快累積的技術債將導致程式包袱越大，也越難維護。然而也因為只要是程式就一定會有 bug ，而越晚修復 bug 的成本越高，因此在各個開發團隊中，希望有效降低軟體維護成本最佳的方式，就是下列兩種：
  1. 提早發現 bug 並進行修復，讓 X 軸的值小一點，自然 Y 軸所代表的成本就低一些。
  2. 讓程式儘可能地好維護一些，以減緩成本上升的曲線斜率。一旦曲線平緩一些，Y 軸所代表的成本自然也會低一點。
而進行 code review 則是有效滿足上面兩個目的：提早發現 bug 且修復，並讓程式好維護一些。

什麼是 Code Review

程式一定有 bug 主要是因為開發人員很容易陷入自己的盲點，常見的盲點有兩種：
  1. 程式是照你寫的跑，不是照你想的跑。
  2. 程式照你想的跑，但你想的是錯的。
要突破上述的盲點，最簡單的方式就是找別人來 review 你開發中或開發完的程式，跟你一起確認程式是否寫的跟你想的一樣，以及確認你想的是對的。
註：當然，review 開發中或開發完的程式所發現 bug 的時間點，就是上圖的 Development 階段，如果希望能在 Design 與 Developer 階段中就發現問題，來讓 bug 根本不會發生，或是在第一時間點就被修復，這就是極限編程 (eXtreme Programming) 中所提倡的搭檔編程 (pair programming)，這在實務上更是挑戰工程師的人性以及管理者的極限，但以 bug 修復成本的角度來看，這的確花費的成本最低。
簡單的說 code review 就是邀請其他人來幫你審查，原始碼上是否存在著不妥之處，例如風格是否與團隊一致、是否有哪邊程式可讀性不佳、有壞味道、不好維護、不好擴充、安全性疑慮、效能不佳、甚至壓根就誤解需求的問題存在。有的時候「三個臭皮匠勝過一個諸葛亮」，臭皮匠有臭皮匠的角度，諸葛亮有諸葛亮的盲點，一定要記住「程式碼是屬於整個團隊的」，不論自己寫的程式再高超、再有效率、再有彈性，如果沒有人可以維護，那就都只是空談。

Code Review 會議的種類

Code review 的方式見仁見智，個人覺得沒有絕對最佳解，只有慢慢 tuning 出最適合團隊的 review 方式，並建立起自己團隊的文化、價值觀與 Code review 的規範和流程。
但可以確定的是，當 code review 的頻率越低，則代表著需要 review 的範圍越大，可能重工的範圍與成本越高，而上線的時間壓力也越緊迫。團隊往往會因為上線時間壓力而導致空頭 review 或略過 review 的動作，大家都知道哪些地方設計不好，卻不進行修改。而 code review 的頻率過高，相對會帶來的 overhead 也會比較多。因此怎麼調整 code review 的頻率與 review 的重點就顯得格外重要。
這邊則針對幾種不同的團隊組成，提供幾種常見的方式供大家參考。
一、團隊中有大量新進工程師，較少的資深工程師
這種時候通常新進工程師只有基本的教育訓練或是由他們自行參考舊的程式與文件，對團隊的開發標準 (coding standard)、開發規範 (code convention)、命名規則、系統架構、系統介接與領域知識不熟悉。他們需要由資深人員帶領，透過實際的例子來對他們進行教育訓練，只是訓練的方式是以 review 新進人員所撰寫的程式碼來進行。
這種情況下 code review 參與人員幾乎是整個開發團隊，好處是透過一次實務的例子，就能讓所有成員用最快的速度了解哪些錯誤不要犯，進而回去修改他們開發中的程式，避免犯同樣的錯誤。壞處則是與會人員一多，花費的時間成本就會相當高，一定要確保 review 會議有效率且有達到效果。
這類型的 code review 頻率建議上限一週一次。當新進工程師開始進入狀況，瞭解團隊文化與開發規範後，就可以減少這類型的 code review 會議，而往其他類型進行。
二、團隊中資深與新進人員比例相當，或是彼此專長領域不相同
這樣的團隊組成，建議可以進行 daily 的 pair review，由資深與新進的工程師進行配對，或是由熟悉不同領域知識的工程師配對，每天花 15~30 分鐘針對今天程式碼異動的部分 (Code Churn)，彼此同步一下。一般一個開發人員每天可以產出新的程式碼（不包含產生器自動產生的部分）行數約莫 200~400 行，因此建議要控制在半小時內 review 完畢，最好也可以把時段固定下來，如同 Scrum 的每日站立會議一樣，儘速且小範圍地針對原始碼提供回饋與建議。而這樣的範圍也是最容易找出 defect 的比例，如下圖所示：
02
▲圖 2 LOC 與 Defect 發現的關係圖（資料來源：https://smartbear.com/SmartBear/media/pdfs/11_Best_Practices_for_Peer_Code_Review.pdf）
這樣配對的好處是，參與的人員較少，可以輕量化地進行 review 與溝通。在 review 過程中，只要出現程式碼看不懂的情況，基本上可以歸類為：
  1. 程式碼是對的，可能是新進人員的技術能力不夠或是不熟悉 domain 的伙伴對需求不夠瞭解。這時候可以針對技術或 domain 不懂的部分進行解說，趁這機會備份彼此的技術與領域知識，這是提升團隊能力與彼此備援的一個重要流程，比起單向的一對多專案分享或教育訓練，來得有效率地多。
  2. 程式碼是有瑕疵的，可能是新進人員違反了開發規範、較難維護擴充或設計出效能較差的演算法，也可能是程式碼的易讀性不夠，讓其他工程師無法輕易瞭解需求與程式碼的設計目的。這時也是協助他們修正與學習的好時機，建立團隊的開發文化，就需要從平時開發的小細節著眼。
不論 review 後的程式碼如何，可以確保的是，這一份程式碼至少有兩個人以上瞭解其意義，也就是擁有共識。並且透過這個機會來提升或備援彼此的領域知識和技術能力，將 code review 的價值最大化。

Code Review 前透過工具的 Preview

在進行 code review 之前，有一些開發規範應該要善用工具來作程式碼分析，以節省 review 過程中所需要花的時間。透過這些工具與定義的標準，可以客觀地審視與協助團隊成員在開發時不會像脫韁野馬、各自為政。下面列出幾個開發規範相關的工具（以 .NET 為例）：
  1. 統一命名標準－詞彙表 (Glossary)：可透過 GoogleDoc、Wiki、Excel 或其他知識管理平台來建立，屬於自己團隊領域知識的相關詞彙，以及開發上的命名習慣。命名，是軟體開發最基本，也是最重要的一件事。
  2. 程式碼風格分析：可透過 StyleCop 來自訂屬於團隊的風格規則範本，讓開發團隊可以隨時檢查程式碼是否有違反風格規則。團隊中程式碼風格的一致性是易讀性與可維護性的基礎之一，風格沒有絕對的對錯，但當規範訂出來之後團隊就應該遵守，規範可以經過團隊同意後進行調整，但程式碼風格的檢查應交給工具來做，才會快速且客觀。如果 code review 還要花時間調整 style ，那就無法做到輕量化敏捷的 review ，時間一旦拉長，與會人員就容易失焦與失去耐心。
  3. 程式碼相似度分析：可透過 Simian 或 VS2012 Premium 以上的版本來進行重複程式碼分析。重複的程式碼一直都是壞味道的基本來源，如何快速的掃描出專案中有哪些程式碼是重複的，可以幫助團隊快速地找到程式碼壞味道，檢查是否違反了單一職責原則 (SRP) 中的同一份職責散落在不同物件中。團隊也可以設定出自己的指標門檻，例如超過20行重複，才需要送出警告。
  4. 程式碼複雜度分析：可透過 SourceMonitor 或 VS2010 Premium 以上的版本中的計算程式碼度量功能來分析循環複雜度。所謂的循環複雜度，簡單的說就是程式碼的分歧路徑，可以想像如果一個方法中程式碼可執行的路徑越多，代表人腦要理解程式碼意義的成本就越高，也代表程式碼可能越難維護。因此複雜度太高也是壞味道之一，直接透過工具分析出複雜度，可以讓開發人員在 code review 之前，就將這些可能不易懂的方法內容修正，以節省 review 的時間，也就是開發人員在開發時就透過工具來幫自己的程式碼做健康檢查，先行用工具 review 的意思。這邊建議分析的報告可以顯示前 15 個最複雜的方法來協助團隊瞭解，目前專案中最複雜的方法是哪一些。而團隊複雜度指標門檻建議可以限定複雜度在 15 以下，也就是複雜度超過 15 時，開發人員應說明原因，確認無法或不需要重構，方可通過審查。
  5. 綜合品質分析：可透過 FxCop 或 Visual Studio 的靜態程式碼分析來進行分析，團隊可依據團隊規範以及專案的性質，建立不同規則集。FxCop 與 Visual Studio 的靜態程式碼分析其實核心是一樣的，如果開發團隊針對基本的安全性分析找不到免費或可信任的工具，建議也可以直接使用 FxCop 中的安全性規則，在 OWASP 上也有推薦使用 FxCop 來進行基本的分析。

上述的工具，除了在開發時期使用，也都可以部署在持續整合伺服器（如 Jenkins、TFS）上每次建置時運作。不管是 daily build 或是 checkin build ，每次程式碼有異動時，團隊就可以在第一時間知道程式碼的品質趨勢是上升或下降。團隊應建立品質文化，當 build failed 或品質開始出現缺陷時，必須用最短的時間修正，否則在破窗效應下，技術債就可能累積越來越多，最後形成焦油坑。
相對大於絕對，趨勢大於數字
在使用程式碼分析工具時，要避免成為數據的奴隸，這些指標報告就如同健康檢查報告，紅字不代表一定有問題，但一直紅字就代表需要關注。而許多團隊可能已經有既有的程式碼或系統 (legacy code)，這時建議大家應瞭解品質指標數據不是絕對的，但一定要守住相對的底限。
也就是不管原本的程式碼品質有多差，在每一次程式碼的異動後，經過每一位開發人員手中，程式碼品質只能更好，不能更糟。因此，這些指標的趨勢要比數字來得重要得多。只要每一次的異動，都能讓品質更上一層樓，哪怕只是一個風格警告的修正，都能幫助產品更好。只要維持住這樣的演進過程，就不用擔心被技術債壓垮，缺陷的趨勢是收斂的，團隊就能更有信心。

Code Review 的注意事項

如前面所說，方式沒有絕對的好壞或對錯，這邊列出一個基本的流程供讀者參考。
Code review 之前的動作
  1. 確保程式碼已經通過靜態程式碼分析並符合指標規範，若存在違反規範的部分，應針對該指標進行說明。
  2. 應先讓與會人員清楚這次要 review 的範圍、需求、流程，若有開發人員已經存在的疑問，也應提前告知與會人員。
  3. 確保程式可以建置或正確執行。
Code review 開始
  1. 先檢查工作清單上的 TODO 是否都被清除了，若沒有，應針對 TODO 進行說明。
  2. 透過 scenario 或測試案例來說明需求，針對異動的部分進行說明。
  3. 商業邏輯的說明只需說明 context 的流程，透過程式碼的命名與抽象層級的設計，說明時其實就跟程式碼命名幾乎一模一樣。
  4. 若有需要修改的部分，建議加上 TODO 相關註解，在 Visual Studio 透過工作清單視窗，就可以避免因紀錄或馬上修改導致 review 時間拉長。
Code review 哪些東西
  1. 程式碼是否滿足業務與營運需求
  2. 程式架構與系統設計是否滿足未來擴充性（確定可能會增加的需求）
  3. 程式碼的易讀性、擴充性與抽象層級一致性
  4. 程式碼效能問題
  5. 程式碼安全問題
  6. Error handling

結論

Code review 很常因為資源、時程、習慣等問題，而被歸類到「我知道這很好，也知道應該要做，但我們無法落實在實務上」的情況。透過上述的簡要說明，整理出幾個重點：
  1. 建立團隊文化與開發規範。
  2. 透過工具來快速且客觀分析程式碼壞味道。
  3. 頻繁且小範圍的進行 review。
  4. Review 過程除了增進程式碼品質以外，更重要的效益在備援與教育訓練團隊成員間的領域知識與技術能力。
  5. 提前準備不能省，讓會議效率最佳化。
  6. 一定要有會議紀錄與待辦事項持續追蹤。
  7. Review 的心態要正確，不應帶著挑戰或雞蛋裡挑骨頭的態度，目的應是彼此學習和讓產品更加進化。

留言

張貼留言

這個網誌中的熱門文章

Json概述以及python對json的相關操作

圖片
什麼是json： JSON(JavaScript Object Notation) 是一種輕量級的數據交換格式。易於人閱讀和編寫。同時也易於機器解析和生成。它基於JavaScript Programming Language, Standard ECMA-262 3rd Edition - December 1999的一個子集。JSON採用完全獨立於語言的文本格式，但是也使用了類似於C語言家族的習慣（包括C, C++, C#, Java, JavaScript, Perl, Python等）。這些特性使JSON成為理想的數據交換語言。 JSON建構於兩種結構： “名稱/值”對的集合（A collection of name/value pairs）。不同的語言中，它被理解為對象（object），紀錄（record），結構（struct），字典（dictionary），哈希表（hash table），有鍵列表（keyed list），或者關聯數組（associative array）。 值的有序列表（An ordered list of values）。在大部分語言中，它被理解為數組（array）。 這些都是常見的數據結構。事實上大部分現代計算機語言都以某種形式支持它們。這使得一種數據格式在同樣基於這些結構的編程語言之間交換成為可能。 jso官方說 ​​明參見：http://json.org/ Python操作json的標準api庫參考：http://docs.python.org/library/json.html 對簡單數據類型的encoding 和decoding： 使用簡單的json.dumps方法對簡單數據類型進行編碼，例如： import json obj = [[ 1 , 2 , 3 ], 123 , 123.123 , 'abc' ,{ 'key1' :( 1 , 2 , 3 ), 'key2' :( 4 , 5 , 6 )}] encodedjson = json.dumps(obj) print repr (obj) print encodedjson 輸出： [[1, 2, 3], 123, 123.123, 'abc', {'ke...
閱讀完整內容

Docker容器日誌查看與清理

1. 問題 docker容器日誌導致主機磁盤空間滿了。 docker logs -f container_name 劈裡啪啦一大堆，很佔用空間，不用的日誌可以清理掉了。  2. 解決方法 2.1 找出Docker容器日誌 在linux上，容器日誌一般存放在 /var/lib/docker/containers/container_id/ 下面，查看各個日誌文件大小的腳本docker_log_size.sh，內容如下： #!/bin/sh echo "======== docker containers logs file size ========" logs=$(find /var/lib/docker/containers/ -name *-json.log) for log in $logs do ls -lh $log done # chmod +x docker_log_size.sh # ./docker_log_size.sh 2.2 清理Docker容器日誌（治標） 如果docker容器正在運行，那麼使用 rm -rf 方式刪除日誌後，通過 df -h 會發現磁盤空間並沒有釋放。 原因是在Linux或者Unix系統中，通過 rm -rf 或者文件管理器刪除文件，將會從文件系統的目錄結構上解除鏈接（unlink）。 如果文件是被打開的（有一個進程正在使用），那麼進程將仍然可以讀取該文件，磁盤空間也一直被佔用。 正確姿勢是 cat /dev/null > *-json.log ，當然你也可以通過 rm -rf 刪除後重啟docker。 接下來，提供一個日誌清理腳本 clean_docker_log.sh ，內容如下： #!/bin/sh echo "======== start clean docker containers logs ========" logs=$(find /var/lib/docker/containers/ -name *-json.log) for log in $logs d...
閱讀完整內容

利用 Keepalived 提供 VIP

Keepalived 是一種基於 VRRP 協定實現的高可靠 Web 服務方案，用於防止單點故障問題。因此一個 Web 服務運作至少會擁有兩台伺服器執行 Keepalived，一台作為 master，一台作為 backup，並提供一個虛擬 IP（VIP），master 會定期發送特定訊息給 backup 伺服器，當 backup 沒收到 master 訊息時，表示 master 已故障，這時候 backup 會接管 VIP，繼續提供服務，來確保服務的高可靠性。 VRRP VRRP（Virtual Router Redundancy Protocol，虛擬路由器備援協定），是一個提供備援路由器來解決單點故障問題的協定，該協定有兩個重要概念： * VRRP 路由器與虛擬路由器：VRRP 路由器是表示運作 VRRP 的路由器，是一個實體裝置，而虛擬路由器是指由 VRRP 建立的邏輯路由器。一組 VRRP 路由器協同運作，並一起構成一台虛擬路由器，該虛擬路由對外提供一個唯一固定的 IP 與 MAC 位址的邏輯路由器。 * 主控制路由器（master）與備援路由器（backup）：主要是在一組 VRRP 中的兩種互斥角色。一個 VRRP 群組中只能擁有一台是 master，但可以有多個 backup 路由器。 VRRP 協定使用選擇策略從路由器群組挑選一台作為 master 來負責 ARP 與轉送 IP 封包，群組中其他路由器則作為 backup 的角色處理等待狀態。當由於某種原因造成 master 故障時，backup 會在幾秒內成為 master 繼續提供服務，該階段不用改變任何 IP 與 MAC 位址。 Keepalived 節點配置 IP ADDRESS ROLE 172.16.1.101 vip 172.16.1.102 master 172.16.1.103 backup 安裝與設定 這 ubuntu 14.04 LTS Server 中已經內建了 Keepalived 可以透過 apt-get 來安裝： $ sudo apt-get install -y keepalived 也可以透過 source code 進行安裝，流程如下： $ sudo apt-get install build-essential libssl-dev $ wge...
閱讀完整內容