四步做好 Code Review
本節課為《如何做好 Code Review》，內容包括：為什麼要做好 Code Review、如何做好 Code Review、例子：Python 程式碼的 Code Review、如何成為一個好的 reviewer 和公司針對 Code Review 的措施五個方面。
為什麼要做好 Code Review
Code Review 是提升程式碼質量的最好方法
強化 Code Review 是提升程式碼質量的第一選擇。
在程式碼開發過程中，我們越早發現問題、定位問題，在修復問題時付出的成本越小。
大約有 50%以上的 bug，都是在做 Code Review 時發現的。前期做好 Code Review，後期將會減少反覆修改等不必要的復工。
Code Review 能夠在團隊內傳遞知識
從知識傳遞的角度看，Code Review 是極為重要的。
做好 Code Review，能夠幫助團隊傳遞知識、溝通交流、互相學習，能夠提升學習能力、提升編寫程式碼能力、提升程式碼質量、提升工作效率、降低專案風險。
另外，基於 codebase 可以使我們瞭解專案全域性，培養系統的思考方式。
Code Review 是輔導怎麼寫程式碼的最好方法
我們要意識到，做 Code Review 可以學習到別人的經驗，同時也可以向別人傳遞我們的經驗。
如果我們想輔導別人，最好的辦法就是讓對方先寫一段程式碼，我們對他的程式碼進行 Code Review。在輔導他人的過程中，我們可以快速地發現問題，從而幫助改進。
做好 Code Review
可以增加公司對最頂級開發者的吸引力
工作中是否有 Code Review 對於公司或團隊來說非常重要。不但對於公司或團隊內的人員有所提升，而且能夠吸引出色的開發者加入開發團隊。
未做好 Code Review 的公司或團隊有如下特點：
①程式碼質量差。
②團隊內人員備份差。
③其人得不到有效的輔導，提高慢。
為什要提高程式碼質量？
①提高程式碼質量可以提高程式碼的可讀性。
②提高程式碼質量可以提高程式碼的複用性和參考性。
③提高程式碼質量可以減少 bug 出現的風險。
④提高程式碼質量可以減少後期補丁的風險。
⑤提高程式碼質量可以降低程式碼失控的風險。
⑥提高程式碼質量可以降低專案重構和升級的麻煩。
\ \ 為什麼要提高寫程式碼的能力
①程式碼能力如果停滯不前，對於個人而言，將導致職業危機。
②程式碼能力如果停滯不前，對於團隊而言，將意味著團隊沒有成長。
Code Review 是一個非常重要的提升程式碼質量和程式碼能力的手段。無論是從個人發展角度，還是團隊發展角度，我們都需要重視 Code Review。
如何做好 Code Review
在 Code Review 中可能發現的問題
→ 拼寫錯誤；
→ 未優化的程式碼；
→ 不必要的複雜程式碼；
→ 已經實現過的程式碼，又重複實現；
→ 註釋不全；
→ case 沒有覆蓋全等等問題。
在 Code Review 中要有一個好的態度
要做到以下幾點
（1）對所有檢查的程式碼邏輯要做到“完全看懂”，對於稽核的程式碼，熟悉程度要做到“如數家珍”。如果在稽核程式碼後，對程式碼的邏輯和背後的原因仍然很模糊，則是一個失敗的 Code Review。
（2）好程式碼的標準，不僅僅是“可以執行通過”，在正確性、可讀性、可重用性、可運維性等方面上，都需要綜合考慮。
（3）建立 Code Review 和寫程式碼一樣重要的意識。即：
①Code Review 和寫程式碼一樣，也有產出，即產出更高質量的程式碼。
② 稽核程式碼在很多情況下比寫程式碼還要辛苦，需要理解和找出問題等。
（4）以提升程式碼質量為最終目標。
（5）要投入足夠的時間和精力。
①稽核程式碼花費的時間經常和寫程式碼一樣多，有時甚至比寫程式碼的時間更多，要有時間意識。
②要有責任意識。如果出現 bug，不僅僅是寫程式碼人員的職責，也不僅僅是 QA 的職責，程式碼稽核者也需要承擔相當大的責任。
在 Code Review 之前，一流程式碼的特性
一流程式碼有以下特性：①高效性；②魯棒性；③簡潔；④簡短；⑤可共享；⑥可測試；⑦可移植；⑧可監控；⑨可運維；⑩可擴充套件。 將以上十條標準進行總結精簡，可歸納為：
①程式碼的正確和效能；
②程式碼的可讀和可維護性；
③程式碼的可運維和可執行；
④程式碼的可共享和可重用；
在 Code Review 時，綜合考慮以上一流程式碼的特性，可以快速提升程式碼質量、提升編寫程式碼的能力等。
在 Code Review 時
需要有對 bad code 進行簡單判斷的能力
除了要了解一流程式碼的特性之外，在 Code Review 時，需要有對 bad code 進行簡單判斷的能力。通常 bad code 有以下特點：
①5 分鐘內不能看懂的程式碼。
不能快速看懂的程式碼，一定是有問題的程式碼，可以先拋回給編寫程式碼人員進行修正。一般一個函式的操作不能超過 6 個 step，如果超過這個數量，則需要重新調整編碼邏輯。
②需要思考才能看懂的程式碼。
好的程式碼閱讀時基本不用動腦子，甚至看註釋就能看懂。
③需要來回翻屏才能看懂的程式碼。
好的程式碼，經常在一屏內就是一個完整的邏輯。
④沒有空行或註釋的程式碼。
在 Code Review 時，發現不會用段落、不會寫註釋的程式碼，肯定不是好的程式設計師寫的程式碼，可以直接打回給編寫程式碼人員進行修正。
Code Review 的注意事項
①在必要時，review 的雙方做面對面的溝通。
面對面溝通並不是單指當面溝通，還包括雲共享、電話、視訊溝通等。在溝通時，對於背景、關鍵點等應進行說明，便於 reviewer 的理解。在必要時，應提供設計文件。
②對於關鍵模組，應該建立 owner 制度。
所有提交的程式碼，必須由 owner 做最終確認。由 owner 掌握全域性，並建立明確的責任關係。
③檢查中發現的問題，要一追到底。
④要注意細節。對每一行提交的程式碼，都要進行檢查。
⑤Code Review 的方式，要小步快跑。每次提交 review 的程式碼量不要太多，降低複雜度。在特殊情況時，比如一個新模組的構建，最好逐步完成，通過多次進行提交。
⑥要為 Code Review 預留出足夠的時間。Code Review VS Coding 的時間，有時可能達到 1:1。在這裡需要考慮到有時會做大的修改，科學地規劃工作量，儘量避免出現時間倒排。
⑦注意每天 review 程式碼的數量不宜過多。
Code Review 的步驟
Code Review 的步驟為以下幾點：
Step1：先看系統全貌
不深究細節，瀏覽系統全貌，理清模組劃分的邏輯、模組間的關係、如何構成的整個系統等。
Step2：進入模組級別
同樣不深究細節，瀏覽模組內的全貌，判斷模組切分是否合理，理清模組內的邏輯，明確關鍵資料、關鍵的類和函式等。
Step3：理清類、函式內部的邏輯。
Step4：進入細節。
比如 Layout、命名等。 人為因素
除了程式碼上的問題，在 Code Review 過程中還會有一些人為因素，例如：
①QA 人員
好的 QA 人員不僅僅會發現系統中的 bug，還會質疑或提出產品需求，挑戰或優化系統架構和實現方式。
②Code Reviewer
好的程式碼稽核人員不僅僅指出程式碼表面的問題，還會檢查系統需求分析的質量、介面或函式定義的合理性、模組劃分的合理性、系統關鍵機制的合理性等。
例子：Python 程式碼的Code Review
以 Python 為例，從 Python 的編碼規範和 Python 程式設計規範的部分說明兩個維度來看一下 Code Review 的細節。這些 Code Review 細節，在其他語言中基本都是相通的。
Python 的編碼規範
（1）程式碼要寫的漂亮。
（2）程式碼要明確直接，不要含蓄表達。
（3）程式碼要簡潔，一個函式可以實現的功能就不要寫兩個函式。
（4）程式碼深奧勝過程式碼複雜。程式碼可以寫的深奧難懂，但是不能寫的過於複雜。
（5）程式碼要平鋪直敘，不要層層巢狀。
（6）程式碼要做到合理間隔。
（7）程式碼可讀性非常重要。
（8）程式碼要有普適性。儘量規避程式碼特殊性，用最簡潔最通用的程式碼來實現。
（9）程式碼要實用。
（10）要重視所有發現的錯誤。
（11）程式碼邏輯要清晰。在含糊混亂的面前，我們要拒絕猜測。讀寫程式碼時，不要出現“好像”、“可能”、“似乎”等猜測。當一段程式碼很難懂的時候，程式碼一定存在問題。
（12）寫程式碼要注重行動。
（13）程式碼實現方法要簡潔。如果一個方法很難解釋，就意味著這個方法存在一定的問題。
（14）要重視名稱空間的使用。
關於 Python 程式設計規範的部分說明
Python 程式設計規範有九個維度。
（1）模組的劃分
我們要對模組有概念，這是整個系統的基礎。
①一個.py 檔案是一個模組。
②模組的劃分對軟體的長期維護非常重要。
③每個模組都應該有特定的功能。
比如：配置檔案的讀取，網頁檔案的寫入，網頁檔案的解析，一個記憶體資料表，一個抓取的執行緒等等。
④多個本應獨立的模組，寫到一個.py 檔案中是常見的錯誤。從 Code Review 角度看，首先就是要看模組切分的對不對。
（ 2 ）資料的封裝
在 Code Review 時，要著重注意資料是否封裝這一問題。
（ 3 ）import
Import 在使用過程中，禁止使用 from xxx import yyy 語法直接匯入類或函式。禁止使用 from xxx import *這樣的方法。這樣做的目標是：容易判斷程式碼中使用外部變數或函式的來源。
如果使用禁止中的語法，會大大增加判斷來源的難度，以及程式碼閱讀的難度。
在 Code Review 時，遇到這種情況，及時將程式碼打回給程式設計人員進行修正。
（ 4 ）異常
對於異常的處理有以下幾點需要注意：
①異常的使用
使用異常前請需要詳細瞭解異常的行為。不要主動丟擲異常，使用返回值。如果一定要拋異常，需要註釋進行說明。
②異常的獲取強制
除非重新丟擲異常，否則禁止使用 except:捕獲所有異常，不建議捕獲 Exception 或 StandardError。
在實際編碼中建議 try 中的程式碼儘可能少，避免 catch 住未預期的異常，掩藏掉真正的錯誤。底線是至少要列印異常的日誌，而不是捕獲後直接 pass 通過。
在對異常進行處理時儘量針對特定操作的特定異常來捕獲。
常犯的錯誤是：一是對 IO 等操作不捕獲異常。二是捕獲異常區域很大。
③函式的返回值
如果函式會丟擲異常，需要在函式的註釋中明確說明。
在 Code Review 時，需要注意上述問題，及時返回給程式設計人員進行修正。
（ 5 ）建構函式
對於建構函式有以下幾點需要注意：
①規範：
類建構函式應該儘量簡單，不能包含可能失敗或過於複雜的操作。
②解讀：
在建構函式中常出現的錯誤是：無法判斷、或捕獲異常。
（ 6 ）函式返回值
對於函式返回值有以下幾點需要注意：
①規範：
函式返回值必須小於等於 3 個。返回值超過 3 個時必須通過 class/namedtuple/dict 等具名形式進行包裝。
②解讀：
a. 多數情況下的錯誤，是因為很多人不會思考和設計函式的語義。
函式描述涉及的三要素為：功能描述、傳入引數描述和返回值描述。
每個函式都應該有足夠明確的語義。基於函式的語義，函式的返回值有三種類型：
第一種型別：在“邏輯判斷型”函式中，返回布林型別的值——True 或 False，表示“真”或“假”。
第二種型別：在“操作型”函式中，作為一個動作，返回成功或失敗的結果——OK 或 ERROR。
第三種類型：在“獲取資料型”函式中，返回一個“資料”，或者返回“無資料/獲取資料失敗”。
b .另外，函式需要有返回值，對於正確或錯誤的情況，在返回值中要有體現。
c .還有一個問題是：Python 的資料格式不需要定義，過於靈活。當程式規模變大、維護週期變長時，會導致後期極難維護。
應對措施是：多寫註釋，寫清楚返回值說明、引數說明。
在 Code Review 時，註釋未寫清楚的程式碼，一定要打回給程式設計人員，進行修正、補註釋。
（ 7 ）程式碼長度
關於程式碼長度有以下幾點需要注意：
①每行不得超過 120 個字元。避免在終端上顯示出現折行。
②函式長度不得超過 100 行。函式過長會增加理解函式邏輯的難度。Python 的函式應儘量控制在 30~40 行之間。
在 Code Review 時，程式碼過長，建議全部打回給程式設計人員進行修正。
（ 8 ）空行、空格
關於空行、空格有以下幾點需要注意：
①空行
檔案及定義之間隔兩個空行。比如類或全域性函式。類方法之間隔一個空行。
②空格
逗號、分號、冒號前不加空格，後邊加一個空格。所有二元運算子前後各加一個空格。
在 Code Review 時，需要著重注意空行和空格。空行和空格不是可有可無的。空行和空格的存在，是為了增加可讀性。不好讀的程式碼，一律打回給程式設計人員進行修正。
（ 9 ）註釋
關於註釋有以下幾點需要注意：
Python 中的註釋有一個特殊之處是 docstring，docstring 要和“＃”注意區分開。
相關規範有：
①使用 docstring 描述 module、 function 、class 和 method 介面時，docstring 必須用三個雙引號括起來。
②對外介面部分必須用 docstring 描述。內部介面視情況自行決定是否寫 docstring。
③介面的 docstring 描述至少包括功能簡介、引數、返回值。如果可能丟擲異常，必須使用註釋進行說明。
④每個檔案都必須有檔案宣告，檔案宣告必須包括以下資訊：版權宣告、功能和用途簡介、修改人及聯絡方式。
在 Code Review 時，不符合上述規範的，及時打回給程式設計人員進行修正。
如何成為一個好的 reviewer
程式碼稽核的質量，和稽核者的程式碼能力直接相關。程式碼稽核的質量差，反映的是稽核者的程式碼水平。如果作為一個程式碼稽核員不會寫程式碼，就要承認真相，並且要不斷提高自己的程式碼能力。
在這裡推薦一些學習資料幫助大家進行學習。
①關於程式碼的書籍：《編寫可讀程式碼的藝術》，《程式碼整潔之道》。
②綜合的書籍：《程式碼大全》，《201 principles of software development》。
③其他：《程式碼的藝術》課程，Python Good Coder 考試指南。
公司針對 Code Review 的措施
1、建立高效可運營的程式碼稽核機制，提升程式碼質量，降低程式碼評審成本。
①基於平臺：icode+bugbye
②程式碼檢查規則分級，分為 ERROR、WARNING、ADVICE 三類，對 ERROR 級別阻塞提交。
③通過統計資料驅動程式碼檢測規則的優化。
2、通過工程能力地圖考察專案的 Code Review 情況。
3、所有的 Code Review 行為，都基於 icode 平臺進行。良好的工具可以幫助更好的進行程式碼稽核