京東雲開發者｜代碼評審的價值和規範

評審目的

代碼評審的目的就是為了保證公司整體代碼的健康狀況随着不斷疊代，始終保持一個較高的水準，所有在評審中使用的工具和流程都應是為此目的而設計的。

評審原則

• 鼓勵質疑
• 保持代碼風格，遵守開發規範
• 優先設計原則，尊重個人偏好
• 重視每一行代碼
• 盡可能采用面對面的形式

評審時機

研發流程應該是嚴密的、有節奏的，而個體的代碼品質會影響整體傳遞進度，是以請第一時間啟動代碼評審，最晚不要超過早期測試階段。

如果是異步評審的機制，評審過程最好不要超過一個工作日，如果評審時間較長，請在開始評審時進行初步回報。

評審範圍

1. 功能

這個Change List是否達到了預期目标？

并發、資料權限、性能、競态條件等一系列邊緣異常是否合理規避？

2. 複雜性

新增的複雜是否是值得的？

複雜設計的實作是否是可讀的？

抽象定義是否是優雅整潔的？

鼓勵通過設計提高可擴充性，但不可“面向未來做設計”，二者之間的界限應該是：是否能夠看到明确的演進方向（actual shape）和需求

​

3.單元測試

是否有單元測試？

單元測試是否具有良好的可讀性？

每一個測試是否有斷言？

是否能覆寫盡可能多的邏輯分支？

4. 命名

命名是否符合規範，且具有良好可讀性？

命名是否能充分表達一個項是什麼、用來做什麼？

5. 注釋

注釋内容是否是必須的？

注釋資訊是否全面表述對應代碼的意義？如果發現注釋難以解釋這段代碼，那麼很大機率上這段代碼應該簡化或者重構。

注釋資訊應表達代碼的用處，而不是解釋代碼在幹什麼

6. 代碼風格

鼓勵對代碼風格提出改進建議，但請提及這是一項錦上添花的建議，切不可作為評審通過與否的判定條件。

如果使用評審工具，請在評論前标注​

​Nit:​

​，以辨別這是一項Nitpick（吹毛求疵）的建議。

7. 文檔

是否同時建立了或修改了相關文檔？

文檔格式是否與原項目保持一緻？

8. 上下文

修改的内容是否影響原業務邏輯的上下遊依賴？

修改的内容是否導緻代碼品質下降，甚至系統架構腐化？

9. 優秀的代碼設計

請不要忽略change list中你覺得不錯的部分，肯定優秀設計比指出錯誤更有價值。

評審尺度

不要為了提高評審速度而犧牲代碼評審的标準，團隊内的代碼評審應該是一個持續改進的過程，發現問題、解決問題、避免問題，這種正向循環會為研發流程的每一步都帶來收益。

如果因為各種原因确實需要加速評審環節，可以按照重要程度降低一部分評審标準。但請在合适的時間，對這部分代碼進行重新評審，項目進度緊張不應成為降低代碼品質的理由。

如何解決評審意見沖突

評審是對他人工作進行評判，難以避免意見相左的情況發生，通常研發人員會有非常多的理由拒絕評審建議。

1. 誰是對的

如果研發人員認為評審結果有問題，評審人員請優先思考開發者是不是對的，畢竟他們“離代碼更近”。

如果評審人員認為評審結果是正确的，合理、适當、禮貌的讨論，會讓真相更清晰。

研發人員的反感情緒通常是因為提出問題的方式，而不是對代碼品質的堅持。

2. 稍後再解決

研發人員最常見的拒絕原因，就是進度緊張，希望能夠先做妥協，承諾後續修正。

但通常之後不會再去做這件事，這并非完全是責任心的問題，而是因為研發人員通常非常繁忙，修複這件事就容易被遺忘。

是以最好将評審建議盡快修複。

3. 評審過于嚴格

如果評審尺度嚴格導緻研發人員抱怨，那麼禮貌的堅持非常有必要，嚴格的代碼評審有助于産出優秀的代碼。

總結

參考：

1. ​​​https://google.github.io/eng-practices/review​​