作者：京東物流 馮志文

前言

本文參考《京東JAVA代碼規(guī)范-V1.1》&Google代碼評(píng)審工程實(shí)踐方法論，結(jié)合團(tuán)隊(duì)代碼評(píng)審的實(shí)踐經(jīng)驗(yàn)整理成文檔，這份文檔是我們團(tuán)隊(duì)集體經(jīng)驗(yàn)的結(jié)晶。我相信公司其他部門也有類似的經(jīng)驗(yàn)和最佳實(shí)踐。希望通過互相交流和學(xué)習(xí)，共同提高代碼質(zhì)量，進(jìn)而提高系統(tǒng)的穩(wěn)定性。

名詞解釋：

CL： “changelist”修改列表，它是提交到coding版本控制工具中的一次代碼修改（即將審核的代碼）

CR：CodeReview代碼評(píng)審

一、為什么需要CR

代碼質(zhì)量是軟件質(zhì)量的基石

1.我們進(jìn)行代碼評(píng)審的目的是為了提升代碼質(zhì)量，盡早發(fā)現(xiàn)潛在缺陷與BUG，降低修復(fù)成本。同時(shí)，這也有助于促進(jìn)團(tuán)隊(duì)內(nèi)部的知識(shí)共享，幫助更多人更好地理解我們的系統(tǒng)。

2.從系統(tǒng)的角度來看，代碼審查可以幫助我們提前發(fā)現(xiàn)問題，減少bug，提高穩(wěn)定性，避免到處救火的情況發(fā)生。

3.從開發(fā)人員來看，代碼評(píng)審是一個(gè)逐步改正不良習(xí)慣的過程，可以提高編碼、設(shè)計(jì)、架構(gòu)能力。讓他們從自身犯過的錯(cuò)誤中學(xué)習(xí)，并從他人的思路中成長(zhǎng)。

4.從評(píng)審者來看，這也是一個(gè)學(xué)習(xí)他人編碼能力的機(jī)會(huì)。我們可以從他們的經(jīng)驗(yàn)和技巧中汲取養(yǎng)分，不斷提高自己的專業(yè)素養(yǎng)。

5.從團(tuán)隊(duì)管理來看，代碼評(píng)審提高團(tuán)隊(duì)凝聚力，熟悉彼此的模塊業(yè)務(wù)。這將使我們更加團(tuán)結(jié)協(xié)作，降低因人員流失帶來的成本和風(fēng)險(xiǎn)。

......

請(qǐng)記住，代碼評(píng)審不是批斗會(huì)。我們的目標(biāo)是針對(duì)代碼本身，而不是針對(duì)人。我們應(yīng)該以建設(shè)性的方式提出問題和改進(jìn)意見，以幫助開發(fā)人員提高編程技能和整體水平。

最后，請(qǐng)確保團(tuán)隊(duì)所有開發(fā)者都理解并接受這個(gè)流程。如果團(tuán)隊(duì)有人對(duì)此產(chǎn)生抵觸或反感，那么這個(gè)目的就無法實(shí)現(xiàn)。小組剛開始代碼評(píng)審也是這樣，大家總覺得不好意思指出別人的不合理之處。因此，請(qǐng)大家共同努力，讓代碼評(píng)審成為我們團(tuán)隊(duì)文化的一部分。

二、CR流程規(guī)范

CR前提條件：

1.本地通過IDEA各種插件檢查一般性的錯(cuò)誤。比如使用JoyCoder、京東編碼規(guī)約、Sonar等

2.自測(cè)通過，確保基本功能流程沒問題

將CR前置，避免到最后上線的時(shí)候合并到Master做CR。履約需求上線CR至少經(jīng)過2輪，第一次是提測(cè)前，最后一輪是上線前。每一輪的側(cè)重點(diǎn)不一樣。流程如下：

備注：Dev分支主要作用local代碼庫的遠(yuǎn)程備份，這個(gè)備份動(dòng)作是通過不斷commit&push完成，所以不用擔(dān)心代碼丟失。Feature分支承擔(dān)功能測(cè)試和CR的作用，因?yàn)橛蠨ev一層屏蔽了中途反復(fù)地修改，使得提交地PR更為清晰。Master是上線使用的分支。

第一次CR：

項(xiàng)目提測(cè)前（合并到feature分支）

1.為什么是測(cè)試前？

2.如果都測(cè)試完成了要上線了，CR的意義在哪里？CR發(fā)現(xiàn)的很多問題還改不改？

3.提測(cè)前CR反饋的問題細(xì)致全面，研發(fā)可以及時(shí)修復(fù)。

中間CR：

（合并到feature分支）

1.主要是修復(fù)測(cè)試提的BUG之類，或者這個(gè)需求很久了，需要重新拉取最新的線上代碼master

最后一次CR：

上線前（合并master主干）

1.這時(shí)候核心是CR代碼沖突，代碼是否有遺漏，配置是否準(zhǔn)確？上線是否有其他風(fēng)險(xiǎn)點(diǎn)？

切記代碼上線前的最后一次CR后，務(wù)必需要經(jīng)過測(cè)試回歸驗(yàn)證，引流驗(yàn)證等，以防合并代碼遺漏等情況。對(duì)上線前代碼再次回歸驗(yàn)證沒問題后才可以上線

代碼評(píng)審 整個(gè)過程 分為 評(píng)審者和開發(fā)中。接下來分別解釋下評(píng)審者指南和開發(fā)者指南。

三、代碼評(píng)審者指南

在進(jìn)行代碼評(píng)審時(shí)，我們可以從不同的角度出發(fā)，包括評(píng)審者和開發(fā)者的角度來進(jìn)行。

首先，從評(píng)審者的角度來看，我們需要了解一些評(píng)審的指南。這些指南包括：

1.哪些人可以參與代碼審核？

2.評(píng)審方式有哪些？標(biāo)準(zhǔn)是什么？

3.評(píng)審者應(yīng)該關(guān)注哪些？

1、哪些人可以參與代碼審核呢？

1.小組長(zhǎng)TL：從團(tuán)隊(duì)角度出發(fā)，需要有全局觀，重點(diǎn)關(guān)注【穩(wěn)定性】【代碼可讀性】等

2.架構(gòu)師：從系統(tǒng)架構(gòu)出發(fā)，核心關(guān)注【代碼思路是否和架構(gòu)設(shè)計(jì)一致】

3.核心骨干：為了確保代碼質(zhì)量和項(xiàng)目穩(wěn)定性，我們通常會(huì)選擇團(tuán)隊(duì)中最優(yōu)秀的代碼審核者來進(jìn)行審核。這個(gè)人應(yīng)該具備足夠的經(jīng)驗(yàn)和技能，能夠在你期望的時(shí)間內(nèi)對(duì)審核工作負(fù)責(zé)。

4.團(tuán)隊(duì)成員：如果長(zhǎng)期是核心骨干CR，這樣會(huì)導(dǎo)致團(tuán)隊(duì)其他人員參與度不高，需鼓勵(lì)團(tuán)隊(duì)其他成員參與代碼審核

前提條件

1.作為評(píng)審者，我們需要對(duì)項(xiàng)目的需求和設(shè)計(jì)文檔有充分的了解，以便更好地理解代碼的目的和實(shí)現(xiàn)方式。

2.評(píng)審者需要對(duì)評(píng)審的代碼負(fù)責(zé)，而不是不看直接merge通過之類。

注意事項(xiàng)

1.有時(shí)候一個(gè)代碼審核者無法覆蓋整個(gè)CL，因?yàn)槠渲锌赡馨嗟拇a文件或者需要不同的技術(shù)背景來理解。在這種情況下，我們需要多位審核者參與審核，以確保能夠覆蓋所有的代碼文件。我們應(yīng)該考慮使用多個(gè)審核者來互相檢查和驗(yàn)證代碼質(zhì)量，從而減少潛在的錯(cuò)誤和漏洞。

2.不建議剛加入團(tuán)隊(duì)成員不足3個(gè)月并且還不熟悉業(yè)務(wù)的新人，具體可根據(jù)團(tuán)隊(duì)情況考慮。

2、評(píng)審的方式有哪些？

1.線上Coding平臺(tái)（占比90%）：這種方式優(yōu)點(diǎn)是京Me自動(dòng)通知方便快捷，可以節(jié)省時(shí)間和成本。但是需要注意的是，由于Coding平臺(tái)缺乏Idea其他內(nèi)容上下文，前期評(píng)審者可能不太習(xí)慣，需要慢慢適應(yīng)。

2.線下評(píng)審

1.面對(duì)面審核（占比5%）：適合改動(dòng)較小，這種方式的優(yōu)點(diǎn)是有疑問時(shí)可以隨時(shí)提問并得到解答，可以直接了解開發(fā)者的思路和意圖，有助于發(fā)現(xiàn)更深層次的問題。但是需要注意的是，這種方式需要耗費(fèi)較多的時(shí)間和精力。

2.團(tuán)隊(duì)組會(huì)審批（占比5%）：對(duì)于大型項(xiàng)目需求或者黃金核心鏈路有風(fēng)險(xiǎn)的需求，除了線上評(píng)審?fù)猓覀兛梢跃€下再次Review把控。線下的核心是把控上線風(fēng)險(xiǎn)點(diǎn)（Joyspace列出相關(guān)事項(xiàng)），通過團(tuán)隊(duì)內(nèi)部的討論和協(xié)作來提高代碼質(zhì)量。這種方式的優(yōu)點(diǎn)是可以充分發(fā)揮團(tuán)隊(duì)的力量，共同解決潛在問題。但是需要注意的是，由于參與人數(shù)較多，可能需要較長(zhǎng)的時(shí)間來完成評(píng)審過程。Promise遇到牽扯較大、核心鏈路風(fēng)險(xiǎn)高的需求會(huì)采用線下Review風(fēng)險(xiǎn)事宜。

總之，在選擇代碼審核方式時(shí)，我們應(yīng)該根據(jù)具體情況進(jìn)行選擇。同時(shí)，我們也應(yīng)該注意及時(shí)反饋評(píng)審結(jié)果和建議，以便開發(fā)者能夠及時(shí)修正問題并提高代碼質(zhì)量。

3、CR的標(biāo)準(zhǔn)是什么？

代碼審核的目的是保證持續(xù)改進(jìn)代碼庫質(zhì)量。

1.原則上，如果提交的代碼能顯著提高質(zhì)量，即使不完美也批準(zhǔn)。

2.審核者應(yīng)分享知識(shí)，寫一些有助于學(xué)習(xí)的評(píng)論。

3.涉及設(shè)計(jì)的問題應(yīng)基于原則權(quán)衡，而非個(gè)人喜好。

4.如果沒有規(guī)則，讓作者與現(xiàn)有代碼保持一致，不惡化系統(tǒng)質(zhì)量。

4、代碼審核步驟有哪些？

1.全面了解 CL背后（需求、技術(shù)改造）。這個(gè) CL 是否有意義？它是否包含好的描述？

2.綜觀整個(gè) CL 中最重要的部分。從整體來看，設(shè)計(jì)是否合理？

1.找到包含 CL “主體”部分的文件。通常，如果一個(gè)文件包含大量的邏輯修改，那么它就是 CL 的主體部分。先審視這些主體部分有助于為其他部分理出上下文。如果 CL 太大，很難找到主體部分的位置，可以征詢開發(fā)者的建議，你應(yīng)該先看哪些部分，并建議他把一個(gè)CL拆分多個(gè)小CL，小步快跑（功能獨(dú)立的可設(shè)置為一個(gè)小CL。比如web頁面操作的分為一個(gè)小CL，定時(shí)任務(wù)Task相關(guān)的是一個(gè)小CL，API接口部分是一個(gè)小CL）

2.如果發(fā)現(xiàn)CL 中有一些重要的設(shè)計(jì)缺陷或設(shè)計(jì)問題，立即給出反饋，即使現(xiàn)在還沒來得及審核其他部分。實(shí)際上，審核其他部分很有可能是浪費(fèi)時(shí)間。只要這個(gè)設(shè)計(jì)問題足夠大，在重新設(shè)計(jì)時(shí)，其他代碼很有可能會(huì)消失或變得無關(guān)緊要了。

3.以合適的順序檢查CL的其他部分。在確認(rèn) CL 沒有重要設(shè)計(jì)問題之后，整理出審視文件的順序，并確保不會(huì)遺漏任何文件。通常，在審視了主要文件之后，最簡(jiǎn)單的方式就是按照代碼審核工具呈現(xiàn)出來的順序遍歷每個(gè)文件。有時(shí)候，先閱讀測(cè)試代碼更有幫助，因?yàn)榭戳藴y(cè)試代碼之后，你就明白這個(gè) CL 的期望行為是什么。

5、代碼審核者應(yīng)該關(guān)注哪些？

確保審核了每行代碼，并且查看上下文，確保你正在提升代碼質(zhì)量，當(dāng)開發(fā)者的 CL 中包含好東西時(shí)，稱贊他們。

5.1、兼容性

審核者需要判斷，本次CL是否會(huì)影響線上現(xiàn)有功能

1.比如JSF接口出參的位置，是否會(huì)導(dǎo)致上游調(diào)用序列化出錯(cuò)？

2.中間件配置變更，比如數(shù)據(jù)表增加索引，表數(shù)據(jù)量多大，會(huì)不會(huì)增加索引導(dǎo)致數(shù)據(jù)庫阻塞?

3.是否需要增加Ducc開關(guān)技術(shù)，在穩(wěn)定性和代碼復(fù)雜性中均衡考量

5.2、設(shè)計(jì)

1.審核一個(gè) CL 最重要的事情就是考慮它的整體設(shè)計(jì)，代碼是否按照架構(gòu)設(shè)計(jì)方案進(jìn)行編碼？

2.API & DataBase 是否合理

3.這段代碼應(yīng)該放到哪里更合適？它是否可以很好地與系統(tǒng)其他部分集成？

4.還應(yīng)關(guān)注：技術(shù)棧簡(jiǎn)單、統(tǒng)一的控制，避免非必要引入三方框架、組件等，為系統(tǒng)穩(wěn)定性埋下隱患

5.3、功能

1.這個(gè) CL 所實(shí)現(xiàn)的功能與需求期望開發(fā)的功能是一致的嗎？

2.絕大多數(shù)情況，我們期望開發(fā)者在提交 CL 進(jìn)行審核之前，已經(jīng)做過充分的測(cè)試。但作為審核者，在審核代碼時(shí)仍要考慮邊界情況、并發(fā)問題等等。確保消滅那些通過閱讀代碼就能發(fā)現(xiàn)的缺陷。

3.作為審核者，你可以根據(jù)需要親自驗(yàn)證 CL 的功能。僅通過閱讀代碼，你很難理解有哪些改變，對(duì)系統(tǒng)有哪些影響。對(duì)于這種修改，可以讓開發(fā)者演示這個(gè)功能。當(dāng)然，如果方便把 CL 的代碼集成到你的開發(fā)環(huán)境，你也可以自己親自嘗試。

4.在代碼審核過程中，對(duì)功能的考慮還包含一種重要場(chǎng)景：CL 中包含一些“并行計(jì)算”，可能會(huì)帶來死鎖或競(jìng)爭(zhēng)條件。運(yùn)行代碼一般很難發(fā)現(xiàn)這類問題，通常需要（開發(fā)者和審核者）仔細(xì)考慮，以確保不會(huì)引入新的問題。（這也是不要引入并發(fā)模型的一個(gè)好理由，因?yàn)樗赡芤胨梨i或競(jìng)爭(zhēng)條件，同時(shí)也增加了代碼審核和代碼理解的難度。）

5.4、性能

1.這段代碼如果數(shù)據(jù)量大，性能是否有問題？有沒有更好的實(shí)現(xiàn)方式？

案例：多個(gè)for循環(huán)無用業(yè)務(wù)

5.5、復(fù)雜性

1.是不是 CL 可以不必這么復(fù)雜？在 CL 的每個(gè)層次上檢查——哪一行或哪幾行是不是太復(fù)雜了？功能是否太復(fù)雜了？類（class）是否太復(fù)雜了？“太復(fù)雜”的定義是代碼閱讀者不易快速理解。同時(shí)意味著以后其他開發(fā)者調(diào)用或修改它時(shí)，很容易引入新的缺陷。

2.另一種類型的復(fù)雜是過度工程化（也稱為過度設(shè)計(jì)）。開發(fā)者在設(shè)計(jì)代碼時(shí)太過于在意它的通用性，或在系統(tǒng)中加入了目前不需要的功能。審核者應(yīng)該特別警惕過度工程化。鼓勵(lì)開發(fā)者解決 當(dāng)前 應(yīng)該解決的問題，而不是開發(fā)者推測(cè)將來 可能 需要解決的問題。將來的問題，等碰到的時(shí)候，你才能看到它的實(shí)際需求和具體情況，到那時(shí)再解決也不遲。

5.6、日志

日志打印是否簡(jiǎn)明扼要，是否有助于線上問題排查；關(guān)鍵環(huán)節(jié)是否打印了日志

5.7、異常

異常處理，是否符合服務(wù)可用率治理規(guī)范，確保增量代碼不腐化已經(jīng)通過可用率星級(jí)認(rèn)證的接口；

5.8、測(cè)試

1.同時(shí)要求開發(fā)者提供 CL 對(duì)應(yīng)的單元測(cè)試。單測(cè)代碼與開發(fā)代碼應(yīng)放到同一個(gè) CL 中，除非碰到緊急情況

2.確保 CL 中的測(cè)試是正確的、明智的、有用的。測(cè)試代碼并不是用來測(cè)試其自身，我們很少為測(cè)試代碼寫測(cè)試代碼——這就要求我們確保測(cè)試代碼是正確的。

3.當(dāng)代碼出問題時(shí)，是否測(cè)試會(huì)運(yùn)行失敗？如果代碼改變了，是否會(huì)產(chǎn)生誤報(bào)？是否每個(gè)測(cè)試都使用了簡(jiǎn)單有用的斷言？不同的測(cè)試方式是否做了合適的拆分？

謹(jǐn)記：測(cè)試代碼也是需要維護(hù)的代碼。不要因?yàn)椴粫?huì)編譯打包到最終的產(chǎn)品中，就接受復(fù)雜的測(cè)試代碼。

5.9、每行代碼

1.在審核代碼時(shí)，仔細(xì)檢查每行 代碼。某些文件，如數(shù)據(jù)文件、生成的set、get代碼或較大的數(shù)據(jù)結(jié)構(gòu)，可以一掃而過。但是人寫的代碼，如類、功能或代碼塊不能一目十行，我們不應(yīng)假設(shè)它是正確的。有些代碼得尤其小心——這需要你自己權(quán)衡——至少你應(yīng)該確認(rèn)你 理解 這些代碼在做什么。

2.如果代碼很難讀懂，那就放慢審核速度，告訴開發(fā)者你沒讀懂代碼，讓他解釋與澄清，之后繼續(xù)審核。如果你讀不懂代碼，很有可能其他工程師也不懂。實(shí)際上，這么做也是在幫助以后的工程師，當(dāng)他讀到這段代碼時(shí)更容易理解代碼。所以，讓開發(fā)者解釋清楚。

如果你理解這些代碼，但是感覺自己不夠資格審核它，確保找到一個(gè)夠資格的人來審核，尤其是比較復(fù)雜的問題，如安全、并發(fā)、可訪問性等等。

5.10、上下文

1.把 CL 放到一個(gè)更廣的上下文中來看，通常很有用。在審核工具中，我們往往只能看到開發(fā)者修改的那部分代碼。更多時(shí)候從整個(gè)文件的角度來讀代碼才有意義。例如，有時(shí)候你只看到添加了幾行代碼，但從整個(gè)文件來看，你發(fā)現(xiàn)這幾行代碼添加到了一個(gè)100行的方法中。在增加之后，需要把它拆分成更小的方法。

2.把 CL 放到系統(tǒng)的上下文中來考慮也很有用。CL 能提升系統(tǒng)的代碼健康狀況，還是讓系統(tǒng)變得更復(fù)雜、更難測(cè)試？大多數(shù)系統(tǒng)變得很復(fù)雜都是由每個(gè)細(xì)小的復(fù)雜累積而成的，在提交每個(gè) CL 時(shí)都應(yīng)避免讓代碼變得復(fù)雜。

5.11、文檔

1.如果 CL 修改了編譯、測(cè)試、交互、發(fā)布的方式，那么應(yīng)檢查下相關(guān)的文檔是否也更新了，如 README 文件、CF頁面，或其他所有生成的參考文檔。

2.如果 CL 刪除或棄用（deprecate）了一些代碼，考慮是否也應(yīng)刪除相應(yīng)的文檔。如果沒有這些文檔，讓開發(fā)者（ CL 提交者）提供。

5.12、注釋

1.開發(fā)者是否寫了清晰的注釋？是否所有的注釋都是必須的？通常當(dāng)注釋解釋為什么這些代碼應(yīng)該存在時(shí)，它才是必須的，而不是解釋這些代碼做什么。如果代碼邏輯不清晰，讓人看不懂，那么應(yīng)該重寫，讓它變得更簡(jiǎn)單。當(dāng)然，也有例外（例如正則表達(dá)式和復(fù)雜的算法通常需要注釋來說明），但大部分注釋應(yīng)該提供代碼本身沒有提供的信息，如這么做背后的原因是什么。

2.有時(shí)候也應(yīng)該看一下這個(gè) CL 相關(guān)的歷史注釋。例如，以前寫的TODO，現(xiàn)在可以刪掉了；某段代碼修改了，其注釋也應(yīng)隨之修改。

注意，注釋與類、模塊、功能的文檔是不同的，這類文檔應(yīng)該描述代碼的功能，怎樣被調(diào)用，以及被調(diào)用時(shí)它的行為是什么。

5.13、代碼樣式

1.在京東，我們所有的主要編程語言都要遵循京東代碼規(guī)范，確保 CL 遵守代碼樣式指南中的建議。

2.如果發(fā)現(xiàn)某些樣式在代碼樣式指南中并未提及，在注釋中加上“Nit”，讓開發(fā)者知道，這是一個(gè)小瑕疵，他可以按照你的建議去做，但這不是必須的。不要因?yàn)閭€(gè)人的樣式偏好而導(dǎo)致 CL 延遲提交。

3.作者在提交 CL 時(shí)，代碼中不應(yīng)包含較大的樣式改變。為這樣很難比較出 CL 中有哪些代碼修改，其后的代碼合并、回滾會(huì)變得更困難，容易產(chǎn)生問題。如果作者想重新格式化文件，應(yīng)該把代碼格式化作為單獨(dú)的 CL 先提交，之后再提交包含功能的 CL

5.15、好的方面

如果在 CL 中看到一些比較好的方面，告訴開發(fā)者，尤其是當(dāng)你在審核代碼時(shí)添加了評(píng)論，他在回復(fù)你的評(píng)論，嘗試向你解釋的時(shí)候。審核者往往只關(guān)注代碼中的錯(cuò)誤，他們也應(yīng)該對(duì)開發(fā)者的優(yōu)秀實(shí)踐表示鼓勵(lì)和感謝。有時(shí)候，告訴開發(fā)者他們?cè)谀男┓矫孀龅煤芎茫雀嬖V他們?cè)谀男┓矫孀龅貌蛔愀袃r(jià)值。

6、怎樣寫代碼審核的評(píng)論？

1.禮貌，保持友善

2.解釋原因：闡明你的意圖、你正在遵循的最佳實(shí)踐、你在提升代碼健康程度

3.給出明確的信息，指出問題所在，讓開發(fā)者最后做決定。

4.鼓勵(lì)開發(fā)者簡(jiǎn)化代碼，給代碼添加注釋，而不是向你解釋為什么這么復(fù)雜

7、代碼評(píng)論被拒絕，應(yīng)如何處理？

1.開發(fā)者和審核者都可能對(duì)代碼提出修改建議，但應(yīng)先考慮開發(fā)者是否正確。若開發(fā)者正確，可忽略評(píng)論；否則，審核者需解釋建議必要性。

2.若審核者堅(jiān)持修改，即使需額外工作也值得，因?yàn)樘嵘|(zhì)量是持續(xù)過程。

3.有時(shí)需多輪解釋，保持禮貌。

4.常見拒絕原因是想盡快完成，建議現(xiàn)在就開始清理，或分配給自己 bug 以避免遺忘，加上 TODO 注釋和 bug 編號(hào)。

四、代碼開發(fā)者指南

從開發(fā)者的角度來看，我們也需要了解一些開發(fā)者的指南。這些指南包括：

1.遵循編碼規(guī)范和最佳實(shí)踐，編寫良好的CL描述：作為開發(fā)者，我們應(yīng)該遵循編碼規(guī)范和最佳實(shí)踐，確保代碼的質(zhì)量和可讀性。

2.CL提交的原子性，如何定義小CL？

3.如何處理審核者評(píng)論及修改代碼？

本文包含開發(fā)者怎樣讓代碼審核容易通過的最佳實(shí)踐。在讀完本指南后，相信能夠讓你的審核質(zhì)量更高，速度更快。

1、編寫良好的 CL 描述

CL 描述內(nèi)容應(yīng)該提供足夠的信息，讓CR更加清晰。它包含了改了什么 與 為什么 這么修改？

1.1、良好的 CL 描述

附Promise這個(gè)CL，清晰描述了需求PRD（鏈接），及核心邏輯，DUCC開關(guān)及單測(cè)描述

1.2、糟糕的 CL 描述

“修復(fù) bug”是一個(gè)很不恰當(dāng)?shù)拿枋觥Ｄ膫€(gè) bug ？你做了哪些事情來修復(fù)它？通通都沒有。類似糟糕的描述還包括：“增加補(bǔ)丁”，“刪除代碼”，“沒有描述”

2、原子性提交

《持續(xù)交付 2.0》的四大工作原則是：堅(jiān)持少做、持續(xù)分解問題、堅(jiān)持快速反饋和持續(xù)改進(jìn)并衡量。這些原則可以不斷縮短持續(xù)交付“8”字環(huán)的運(yùn)行周期，提升用戶反饋速度，從而提高業(yè)務(wù)的敏捷性。它們?cè)诖a提交與 Code Review 中的應(yīng)用就是：提交的原子性。

2.1、為什么應(yīng)該寫小 CL？

小 CL 有如下優(yōu)點(diǎn)：

1.評(píng)審效率更高：將大段的CL拆分成多個(gè)小段CL。這樣可以讓評(píng)審者更容易集中幾分鐘（5分鐘比30分鐘容易）在關(guān)鍵部分，提高評(píng)審效率。

2.反饋更及時(shí)：如果開發(fā)者花費(fèi)了很大的精力開發(fā)了一個(gè)大 CL，直到審核的時(shí)候才知道整個(gè)開發(fā)的方向錯(cuò)了，那么之前的所有時(shí)間就全浪費(fèi)了。

3.引入新缺陷概率更低： 如果修改的內(nèi)容比較少，自然審核人的效率會(huì)更高，開發(fā)者與審核者都更容易判斷是否引入了新的缺陷。

4.更易于設(shè)計(jì)：完善小 CL 的設(shè)計(jì)和修改要容易得多，多次微小的代碼質(zhì)量提高比一次大的設(shè)計(jì)改變更容易。

5.更容易合并代碼：大 CL 在合并代碼時(shí)會(huì)花費(fèi)很長(zhǎng)的時(shí)間，在合并時(shí)需要花費(fèi)大量時(shí)間，而且在寫 CL 期間可能不得不頻繁地合并。

6.更容易回退：一個(gè)大 CL 開發(fā)的時(shí)間比較長(zhǎng)，這意味從開發(fā)到代碼提交這段期間，代碼文件的變更會(huì)比較多。當(dāng)回退代碼時(shí)，情況會(huì)變得很復(fù)雜，因?yàn)樗兄虚g的 CL 很有可能也需要回退。

請(qǐng)注意：審核者有權(quán)因?yàn)槟愕?CL 太大而拒絕它。

2.2、那么如何定義“小”？

一般而言，一個(gè) CL 的大小就應(yīng)該是獨(dú)立功能的修改。這意味著：

1.盡量將一個(gè)CL的大小最小化，它只做一件事。每個(gè)CL應(yīng)該只關(guān)注一個(gè)特定的功能或任務(wù)，而不是整個(gè)功能。這樣可以使審核者更容易理解和評(píng)估CL的內(nèi)容，并減少不必要的復(fù)雜性和混亂。可與審核者進(jìn)行討論，以確定CL的適當(dāng)大小。可以共同探討CL是否涵蓋了足夠的功能，并且能夠提供足夠的上下文來理解CL的目的和影響。通過溝通和合作，可以找到最佳的平衡點(diǎn)。

2.確保CL中包含了所有必要的信息，以便審核者可以理解CL的目的和內(nèi)容。除了CL本身的代碼之外，還應(yīng)包括對(duì)CL的描述、已存在的代碼或之前已經(jīng)審核過的相關(guān)CL的信息。這樣審核者可以更好地了解CL的背景和上下文，從而做出準(zhǔn)確的判斷。

3.在提交CL之后，確保系統(tǒng)仍然能夠正常運(yùn)行。無論是對(duì)于用戶還是開發(fā)人員來說，系統(tǒng)的正常運(yùn)行是至關(guān)重要的。因此，在編寫CL時(shí)，請(qǐng)確保不會(huì)引入任何破壞性或不兼容的更改。

4.如果代碼難以理解，可能是因?yàn)镃L的大小還不夠小。如果需要添加一個(gè)新的API，最好將其與相應(yīng)的使用方法一起包含在同一個(gè)CL中。這樣可以方便審核者理解如何使用該API，同時(shí)也方便后續(xù)的開發(fā)者使用和維護(hù)。此外，這還可以有效防止提交的API無人使用的情況發(fā)生。

5.定期回顧和改進(jìn)您的CL過程。通過反思和總結(jié)經(jīng)驗(yàn)教訓(xùn)，您可以找到可能存在的問題和改進(jìn)的空間。持續(xù)優(yōu)化您的CL過程將有助于提高整體的開發(fā)效率和代碼質(zhì)量。

沒有直觀的標(biāo)準(zhǔn)判斷 CL “太大”應(yīng)該符合哪些條件。

2.3、什么時(shí)候可以有大 CL？

當(dāng)然，也有一些例外情形，允許 CL 比較大：

?刪除一個(gè)文件與修改一行沒有太大區(qū)別， 因?yàn)樗粫?huì)花費(fèi)審核者太多時(shí)間。

?有時(shí)候，一個(gè)大 CL 可能是由可靠的自動(dòng)代碼重構(gòu)工具生成的，審核者的工作主要是檢查它是否做了它應(yīng)該做的工作。雖然符合以上提到的注意事項(xiàng)（例如合并和測(cè)試），這類 CL 也可能比較大。

2.4、注意事項(xiàng)

1.CL之前研發(fā)通過插件（idea集成JoyCoder，京東Idea插件、sonar等檢查語法之類）檢查并且修復(fù)各種代碼樣式問題。

2.把系統(tǒng)重構(gòu)及技術(shù)改造的單獨(dú)CL

3.把測(cè)試代碼包含到對(duì)應(yīng)功能的 CL中

4.不要破壞編譯，影響他人

3、如何處理審核者的評(píng)論

在發(fā)出 CL 之后，審核者一般會(huì)給出反饋（評(píng)論），讓你修改代碼。以下是一些建議，可以幫助您在代碼審核過程中處理審核者的評(píng)論：

3.1、保持好心態(tài)

1.先思考自己是否有改進(jìn)的空間。仔細(xì)考慮審核者是否在反饋中提供了有價(jià)值的內(nèi)容，可以幫助提高代碼庫的質(zhì)量。你的第一個(gè)問題應(yīng)該永遠(yuǎn)都是，“審核者說得對(duì)嗎？” 如果確認(rèn)你是對(duì)的，那就解釋為什么你的方法比較好。

2.保持冷靜和專業(yè)。無論審核者的評(píng)論是正面的還是負(fù)面的，都要保持冷靜和專業(yè)的態(tài)度。不要將審核者的評(píng)論視為個(gè)人攻擊或人身攻擊，而是將其視為對(duì)您工作質(zhì)量和代碼庫質(zhì)量的建議和改進(jìn)的機(jī)會(huì)。

3.從建設(shè)性的角度去理解評(píng)論。審核者可能以批判性的語氣表達(dá)他們的評(píng)論，但作為開發(fā)者，您應(yīng)該努力從中尋找建設(shè)性的意見和建議。問問自己，“我能從這個(gè)評(píng)論中學(xué)到什么？如何改進(jìn)我的代碼？”然后根據(jù)這些建議來調(diào)整和改進(jìn)您的代碼。

4.不要帶著情緒回復(fù)評(píng)論。在代碼審核過程中，違反專業(yè)禮儀是非常嚴(yán)重的事情。如果您感到生氣、惱火或受到冒犯，最好先離開電腦一會(huì)兒，或者做其他事情來平靜自己的情緒。確保您可以以禮貌和友好的方式回復(fù)審核者的評(píng)論。

5.尊重審核者的專業(yè)知識(shí)和經(jīng)驗(yàn)。審核者通常具有豐富的編程經(jīng)驗(yàn)和專業(yè)知識(shí)，他們的意見和反饋對(duì)于提高您的代碼質(zhì)量和產(chǎn)品的質(zhì)量非常重要。尊重他們的專業(yè)意見，并盡可能采納他們的建議進(jìn)行改進(jìn)。

6.尋求澄清或進(jìn)一步解釋。如果您對(duì)審核者的評(píng)論有任何疑問或不理解的地方，不要猶豫向他們尋求澄清或進(jìn)一步的解釋。這有助于消除任何誤解，并確保您正確理解了對(duì)方的意見和建議。

7.提供適當(dāng)?shù)幕貞?yīng)。在回復(fù)審核者的評(píng)論時(shí)，盡量提供有建設(shè)性的回答和解決方案。如果您不同意對(duì)方的觀點(diǎn)，可以提出您的理由并提出相應(yīng)的解決方案。避免爭(zhēng)論或陷入無意義的爭(zhēng)論中。

8.接受批評(píng)并持續(xù)改進(jìn)。審核者的評(píng)論可能是為了幫助您改進(jìn)自己的工作和代碼庫的質(zhì)量。接受批評(píng)，并將其視為一個(gè)學(xué)習(xí)和成長(zhǎng)的機(jī)會(huì)。通過持續(xù)改進(jìn)和修正錯(cuò)誤，您可以提升自己的編碼能力和產(chǎn)品質(zhì)量。

3.2、修復(fù)代碼

1.澄清代碼本身。當(dāng)審核者表示對(duì)您的代碼中的某些內(nèi)容不理解時(shí)，首先嘗試以清晰和簡(jiǎn)潔的方式澄清代碼的目的和功能。確保您能夠用簡(jiǎn)單明了的語言解釋代碼的邏輯和實(shí)現(xiàn)方式。

2.添加注釋來解釋代碼。如果無法通過澄清代碼本身來解決審核者的疑問，您可以添加適當(dāng)?shù)淖⑨寔斫忉尀槭裁催@段代碼這樣寫。注釋應(yīng)該簡(jiǎn)明扼要地概括代碼的功能、目的和關(guān)鍵步驟，以便其他開發(fā)者能夠更好地理解和維護(hù)代碼。

3.清理和重構(gòu)。如果審核者無法理解某段代碼，很有可能其他的代碼閱讀者也會(huì)遇到相同的困惑。在這種情況下，考慮對(duì)代碼進(jìn)行清理和重構(gòu)，以提高其可讀性和可維護(hù)性。刪除不必要的復(fù)雜性，使用清晰的命名約定和適當(dāng)?shù)拇a結(jié)構(gòu)，以幫助其他開發(fā)者更容易理解和閱讀代碼。

4.鼓勵(lì)開放的溝通和討論。在處理審核者的不理解時(shí)，保持開放和積極的溝通態(tài)度非常重要。與審核者一起探討問題的根源，尋求共同的解決方案，并盡可能提供清晰的解釋和支持。這種開放的溝通有助于建立信任和合作，推動(dòng)問題的解決和改進(jìn)的進(jìn)程。

五、代碼評(píng)審的沖突解決

以下是一些建議，可以幫助您在與審核者之間出現(xiàn)沖突時(shí)進(jìn)行有效的溝通和解決：

1.強(qiáng)調(diào)代碼的重要性。在與審核者討論問題時(shí)，始終強(qiáng)調(diào)代碼的重要性和正確性。指出代碼是解決問題的關(guān)鍵，而不是個(gè)人攻擊或人身攻擊的借口。

2.嘗試達(dá)成共識(shí)。首先，努力與審核者達(dá)成共識(shí)并找到雙方都可以接受的解決方案。這可能涉及妥協(xié)、解釋各自的觀點(diǎn)和理解對(duì)方的立場(chǎng)。通過開放和建設(shè)性的討論，尋找共同的目標(biāo)和原則。

3.參考代碼規(guī)范和CR標(biāo)準(zhǔn)。如果無法達(dá)成共識(shí)，可以參考代碼規(guī)范和CR標(biāo)準(zhǔn)等文檔來提供指導(dǎo)和準(zhǔn)則。這些文檔通常包含最佳實(shí)踐、編碼規(guī)范和代碼審查要求，可以作為解決沖突的參考依據(jù)。

4.面對(duì)面溝通。當(dāng)面臨無法解決的問題時(shí)，考慮面對(duì)面與審核者進(jìn)行溝通。面對(duì)面的會(huì)議可以提供更多的上下文和細(xì)節(jié)，有助于更好地理解彼此的觀點(diǎn)，并更有效地解決問題。確保在會(huì)議之后記錄下討論的結(jié)果，并在代碼審核評(píng)論中進(jìn)行反饋。

5.尋求團(tuán)隊(duì)的支持和意見。如果面對(duì)面的溝通仍然無法解決問題，可以尋求其他團(tuán)隊(duì)成員（如架構(gòu)師、TL）的意見和支持。他們可能能夠提供不同的視角和解決方案，幫助您更好地處理沖突。讓TL參與討論并做出最終決定，以確保問題得到適當(dāng)?shù)慕鉀Q和跟進(jìn)。

6.保持專業(yè)和尊重的態(tài)度。無論遇到什么情況，都要保持專業(yè)和尊重的態(tài)度對(duì)待審核者和整個(gè)團(tuán)隊(duì)。避免爭(zhēng)吵、指責(zé)或情緒化的反應(yīng)，而是以理性和冷靜的方式處理沖突，并致力于找到最佳的解決方案。

六、緊急情況

以下是一些建議，可以幫助您處理緊急的CL和相關(guān)的代碼審核流程：

1.快速響應(yīng)并加快審核流程。在緊急情況下，審核者應(yīng)該優(yōu)先考慮代碼的正確性和解決緊急問題的能力，盡快回復(fù)審核者的請(qǐng)求，并盡力加快審核流程。這可能包括加快代碼評(píng)審、測(cè)試和驗(yàn)證的速度，以及與團(tuán)隊(duì)成員協(xié)調(diào)解決問題的時(shí)間。

2.完成緊急情況后進(jìn)行更全面的審核。一旦緊急情況處理完畢，您可以回過頭來進(jìn)行一次更全面的代碼審核。這次審核可以檢查代碼的整體質(zhì)量和一致性，并確保所有的功能和修復(fù)都按照最佳實(shí)踐進(jìn)行編寫和維護(hù)。

3.記錄和總結(jié)經(jīng)驗(yàn)教訓(xùn)。緊急情況發(fā)生后，及時(shí)記錄下您的處理過程和經(jīng)驗(yàn)教訓(xùn)。回顧這些經(jīng)驗(yàn)可以幫助您改進(jìn)未來的應(yīng)對(duì)策略，并為類似的情況提供參考依據(jù)。

七、CodeReview-AI大模型

1.上面描寫的都是人去CodeReview，但靠人力太費(fèi)事費(fèi)力，而且團(tuán)隊(duì)每個(gè)人的水平不一樣，這樣也會(huì)導(dǎo)致CR的效果也不一樣。所以我們需要思考如何利用科技的力量，比如大模型等工具去CodeReview，通過定義好的代碼規(guī)范和代碼比對(duì)，給出建議等，提升代碼效率的同時(shí)也保障了代碼質(zhì)量。

八、總結(jié)

總之，在進(jìn)行代碼評(píng)審時(shí)，我們需要從評(píng)審者和開發(fā)者的不同角度出發(fā)，關(guān)注不同的方面。通過合理的評(píng)審和開發(fā)指南，提高代碼質(zhì)量和團(tuán)隊(duì)協(xié)作效率。上面描述的方式還需要大家在實(shí)踐過程中進(jìn)行持續(xù)改進(jìn)，并根據(jù)團(tuán)隊(duì)的實(shí)際情況進(jìn)行調(diào)整：

1.考慮團(tuán)隊(duì)的特點(diǎn)和需求。每個(gè)團(tuán)隊(duì)都有自己獨(dú)特的特點(diǎn)和需求。在制定代碼審查方法和流程時(shí)，要充分考慮團(tuán)隊(duì)的規(guī)模、項(xiàng)目類型、開發(fā)語言和技術(shù)棧等因素。確保所選的方法和流程與團(tuán)隊(duì)的實(shí)際情況相適應(yīng)。

2.定期回顧和改進(jìn)。代碼審查是一個(gè)持續(xù)不斷的過程，需要定期回顧和改進(jìn)。定期與團(tuán)隊(duì)成員討論和評(píng)估當(dāng)前的代碼審查方法和流程，了解他們的體驗(yàn)和意見。根據(jù)反饋和經(jīng)驗(yàn)教訓(xùn)進(jìn)行必要的調(diào)整和改進(jìn)。

3.培養(yǎng)學(xué)習(xí)氛圍和文化。代碼審查不僅是為了解決問題和提升代碼質(zhì)量，也是一個(gè)學(xué)習(xí)和成長(zhǎng)的機(jī)會(huì)。鼓勵(lì)團(tuán)隊(duì)成員互相支持、分享知識(shí)和經(jīng)驗(yàn)，并建立一種積極進(jìn)取的學(xué)習(xí)文化。通過培訓(xùn)、分享會(huì)和團(tuán)隊(duì)活動(dòng)等方式來促進(jìn)學(xué)習(xí)和知識(shí)傳遞。

4.保持持續(xù)改進(jìn)的動(dòng)力。代碼審查是一個(gè)長(zhǎng)期而持續(xù)的過程，需要不斷努力和改進(jìn)。保持對(duì)代碼質(zhì)量的關(guān)注和追求卓越的動(dòng)力，將代碼審查視為一個(gè)持續(xù)改進(jìn)的機(jī)會(huì)，并不斷尋求提高團(tuán)隊(duì)整體代碼水平的方法。

本文旨在為大家提供參考和借鑒。同時(shí)也歡迎大家對(duì)文章進(jìn)行指正和建議，以便更好地完善我們的實(shí)踐經(jīng)驗(yàn)。如果您有更好的實(shí)踐經(jīng)驗(yàn)，也歡迎與我們交流分享。謝謝！

參考文獻(xiàn)：

Google Engineering Practices Documentation

谷歌代碼審查指南 譯文：https://jimmysong.io/eng-practices/docs/review/

審核編輯 黃宇