1. 項(xiàng)目緣起與核心定位第一次看到“open-code-review”這個(gè)標(biāo)題我腦子里蹦出來(lái)的第一個(gè)念頭是終于有人把這件事拿出來(lái)正經(jīng)聊了。代碼評(píng)審這件事在大多數(shù)團(tuán)隊(duì)里都處于一個(gè)尷尬的位置——所有人都承認(rèn)它重要但真正做得好的團(tuán)隊(duì)少之又少。要么是評(píng)審流于形式點(diǎn)個(gè)贊就過(guò)要么是評(píng)審變成挑刺大會(huì)提交代碼的人被批得體無(wú)完膚久而久之大家都不敢提PR了?！皁pen-code-review”這個(gè)標(biāo)題我理解它的核心訴求是把代碼評(píng)審這件事從“閉門造車”變成“開放協(xié)作”。這里的“開放”有兩層含義。第一層是對(duì)團(tuán)隊(duì)內(nèi)部開放讓評(píng)審過(guò)程透明化每個(gè)人都能看到別人是怎么評(píng)審的、評(píng)審意見(jiàn)是怎么被處理的形成一種集體學(xué)習(xí)的氛圍。第二層是對(duì)工具鏈開放不綁定某一個(gè)特定平臺(tái)或某一種特定流程而是建立一套可復(fù)用的評(píng)審方法論和工具集讓不同技術(shù)棧、不同規(guī)模的團(tuán)隊(duì)都能找到適合自己的落地方案。這個(gè)項(xiàng)目適合誰(shuí)來(lái)參考我梳理了一下大概有三類人最需要。第一類是技術(shù)團(tuán)隊(duì)的負(fù)責(zé)人或Tech Lead他們需要一套可落地的評(píng)審規(guī)范來(lái)提升團(tuán)隊(duì)整體的代碼質(zhì)量。第二類是剛?cè)胄胁痪玫男氯碎_發(fā)者他們往往不知道評(píng)審到底該看什么、怎么提意見(jiàn)才有效需要一套系統(tǒng)的入門指引。第三類是對(duì)開源社區(qū)貢獻(xiàn)感興趣的開發(fā)者他們需要理解在開放協(xié)作環(huán)境下代碼評(píng)審的流程和溝通方式跟公司內(nèi)部有什么不同。我見(jiàn)過(guò)太多團(tuán)隊(duì)在代碼評(píng)審上踩坑了。有的團(tuán)隊(duì)把評(píng)審當(dāng)成形式主義PR提上去三天沒(méi)人理最后自己合并了事。有的團(tuán)隊(duì)評(píng)審標(biāo)準(zhǔn)完全不統(tǒng)一A評(píng)審員覺(jué)得命名要駝峰B評(píng)審員覺(jué)得下劃線更好提交者夾在中間無(wú)所適從。還有的團(tuán)隊(duì)評(píng)審意見(jiàn)提得倒是挺多但全是“這里改一下”“那里優(yōu)化一下”這種模糊表述提交者根本不知道從何下手。這些問(wèn)題歸根結(jié)底都是因?yàn)槿鄙僖惶组_放的、可操作的評(píng)審框架?！皁pen-code-review”要解決的就是把這些散落在各個(gè)團(tuán)隊(duì)里的最佳實(shí)踐和踩坑經(jīng)驗(yàn)整理成一套開放的知識(shí)體系和工具集。它不是要發(fā)明什么新概念而是把已經(jīng)被驗(yàn)證有效的方法論系統(tǒng)化、可操作化。接下來(lái)我會(huì)從設(shè)計(jì)思路、核心細(xì)節(jié)、實(shí)操流程、常見(jiàn)問(wèn)題幾個(gè)維度把這套東西拆開揉碎了講清楚。2. 整體設(shè)計(jì)與思路拆解2.1 為什么代碼評(píng)審需要“開放”框架傳統(tǒng)代碼評(píng)審最大的問(wèn)題是什么我認(rèn)為是信息不對(duì)稱。提交代碼的人不知道評(píng)審者會(huì)關(guān)注什么評(píng)審者不知道提交者的設(shè)計(jì)意圖是什么雙方在一個(gè)信息不完整的條件下進(jìn)行溝通效率自然低下。更糟糕的是很多團(tuán)隊(duì)的評(píng)審標(biāo)準(zhǔn)只存在于資深開發(fā)者的腦子里新人只能靠一次次被指出問(wèn)題來(lái)“悟”學(xué)習(xí)成本極高。“open-code-review”的設(shè)計(jì)思路核心就是打破這種信息不對(duì)稱。它把評(píng)審標(biāo)準(zhǔn)顯性化、把評(píng)審流程透明化、把評(píng)審經(jīng)驗(yàn)文檔化。具體來(lái)說(shuō)它包含三個(gè)層面的設(shè)計(jì)。第一個(gè)層面是評(píng)審清單的標(biāo)準(zhǔn)化。與其讓每個(gè)評(píng)審者憑感覺(jué)去挑問(wèn)題不如建立一套分門別類的檢查清單。比如安全性檢查、性能檢查、可讀性檢查、測(cè)試覆蓋檢查等等。每個(gè)類別下面列出具體的檢查項(xiàng)評(píng)審者按圖索驥既不會(huì)遺漏重要問(wèn)題也不會(huì)在細(xì)枝末節(jié)上過(guò)度糾結(jié)。第二個(gè)層面是評(píng)審意見(jiàn)的結(jié)構(gòu)化。我見(jiàn)過(guò)太多“這里改一下”這種無(wú)效意見(jiàn)了。結(jié)構(gòu)化的評(píng)審意見(jiàn)應(yīng)該包含問(wèn)題描述、問(wèn)題位置、嚴(yán)重程度、建議方案、參考示例。這樣提交者拿到意見(jiàn)后能快速理解問(wèn)題所在也知道該怎么改。第三個(gè)層面是評(píng)審過(guò)程的透明化。所有的評(píng)審討論都公開進(jìn)行不搞私下溝通。這樣做的好處是其他人可以看到評(píng)審的思考過(guò)程從中學(xué)習(xí)評(píng)審方法。同時(shí)公開的討論也更容易沉淀為團(tuán)隊(duì)知識(shí)后續(xù)遇到類似問(wèn)題時(shí)可以直接查閱。2.2 工具選型與平臺(tái)無(wú)關(guān)性設(shè)計(jì)“open-code-review”在工具選型上有一個(gè)很重要的原則平臺(tái)無(wú)關(guān)。我見(jiàn)過(guò)太多團(tuán)隊(duì)把評(píng)審流程跟某一個(gè)特定平臺(tái)綁死結(jié)果平臺(tái)一換整個(gè)流程就要推倒重來(lái)。所以這個(gè)項(xiàng)目的設(shè)計(jì)從一開始就考慮了跨平臺(tái)的兼容性。在代碼托管平臺(tái)的選擇上主流的幾個(gè)平臺(tái)都支持Pull Request或Merge Request機(jī)制這是代碼評(píng)審的基礎(chǔ)設(shè)施。但不同平臺(tái)的評(píng)審功能有差異有的支持行內(nèi)評(píng)論有的支持建議修改有的支持評(píng)審模板。為了做到平臺(tái)無(wú)關(guān)我們需要把評(píng)審流程抽象成幾個(gè)核心環(huán)節(jié)提交、分配、評(píng)審、討論、修改、合并。每個(gè)環(huán)節(jié)的具體操作可以因平臺(tái)而異但流程本身是統(tǒng)一的。在評(píng)審工具的選擇上我建議采用“輕量級(jí)工具組合”的策略。不要試圖找一個(gè)全能型的評(píng)審工具而是把幾個(gè)專注單一功能的工具組合起來(lái)使用。比如用代碼格式化工具自動(dòng)檢查代碼風(fēng)格用靜態(tài)分析工具自動(dòng)發(fā)現(xiàn)潛在缺陷用測(cè)試覆蓋率工具檢查測(cè)試完整性然后人工評(píng)審專注于邏輯正確性和設(shè)計(jì)合理性。這樣分工明確效率最高。這里有一個(gè)我踩過(guò)的坑要分享曾經(jīng)有一個(gè)團(tuán)隊(duì)試圖把所有評(píng)審規(guī)則都寫進(jìn)自動(dòng)化檢查工具里結(jié)果規(guī)則越加越多最后提交一個(gè)PR要等十幾分鐘才能跑完所有檢查開發(fā)者怨聲載道。后來(lái)他們調(diào)整了策略把檢查分成“必須通過(guò)”和“建議通過(guò)”兩級(jí)必須通過(guò)的檢查只保留最核心的幾條其他的都放到建議級(jí)別不阻塞合并流程。這個(gè)調(diào)整之后開發(fā)者的抵觸情緒明顯下降了。2.3 評(píng)審粒度與頻率的平衡策略代碼評(píng)審的粒度控制是一個(gè)很容易被忽視但影響巨大的問(wèn)題。評(píng)審粒度太粗一個(gè)PR包含幾十個(gè)文件的改動(dòng)評(píng)審者根本看不過(guò)來(lái)只能草草了事。評(píng)審粒度太細(xì)每個(gè)PR只改幾行代碼評(píng)審頻率過(guò)高評(píng)審者疲于應(yīng)付同樣會(huì)影響評(píng)審質(zhì)量。我的經(jīng)驗(yàn)是一個(gè)理想的PR應(yīng)該控制在200到400行代碼改動(dòng)之間。這個(gè)規(guī)模下評(píng)審者可以在15到30分鐘內(nèi)完成一次有質(zhì)量的評(píng)審既不會(huì)因?yàn)樘蠖z漏問(wèn)題也不會(huì)因?yàn)樘《l繁打斷工作節(jié)奏。當(dāng)然這個(gè)數(shù)字不是絕對(duì)的如果是緊急修復(fù)或者配置文件的改動(dòng)可以適當(dāng)放寬。除了代碼行數(shù)還有一個(gè)維度是功能完整性。一個(gè)PR應(yīng)該對(duì)應(yīng)一個(gè)完整的功能點(diǎn)或一個(gè)獨(dú)立的修復(fù)項(xiàng)不要把多個(gè)不相關(guān)的改動(dòng)混在一起。我見(jiàn)過(guò)有人把代碼重構(gòu)、功能新增、bug修復(fù)全塞在一個(gè)PR里評(píng)審者根本分不清哪些改動(dòng)是必要的、哪些是順帶的評(píng)審效率極低。在評(píng)審頻率上我建議采用每日固定時(shí)段評(píng)審的策略。比如每天上午十點(diǎn)和下午三點(diǎn)各花半小時(shí)集中處理評(píng)審請(qǐng)求。這樣做的好處是評(píng)審者可以集中注意力不會(huì)被頻繁的評(píng)審請(qǐng)求打斷工作流。同時(shí)提交者也知道什么時(shí)候能拿到評(píng)審意見(jiàn)可以合理安排自己的開發(fā)節(jié)奏。注意不要搞“隨時(shí)提交隨時(shí)評(píng)審”的模式那樣會(huì)讓評(píng)審者變成救火隊(duì)員嚴(yán)重影響深度工作效率。集中評(píng)審時(shí)段是經(jīng)過(guò)驗(yàn)證的有效做法。3. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)3.1 評(píng)審清單的制定與迭代方法評(píng)審清單是“open-code-review”的核心工具之一。一份好的評(píng)審清單應(yīng)該像飛機(jī)起飛前的檢查單一樣條目清晰、可操作、不遺漏關(guān)鍵項(xiàng)。我建議把評(píng)審清單分成幾個(gè)大類每個(gè)大類下面再細(xì)分具體檢查項(xiàng)。第一類是正確性檢查。這是最基礎(chǔ)也是最重要的檢查類別。包括代碼邏輯是否實(shí)現(xiàn)了預(yù)期功能邊界條件是否處理異常情況是否考慮并發(fā)場(chǎng)景是否安全數(shù)據(jù)類型是否匹配空值是否處理這些檢查項(xiàng)看起來(lái)簡(jiǎn)單但實(shí)際評(píng)審中遺漏率很高。我建議把正確性檢查放在評(píng)審流程的第一步因?yàn)槿绻壿嫳旧碛袉?wèn)題后面的風(fēng)格檢查、性能檢查都是白費(fèi)功夫。第二類是安全性檢查。包括用戶輸入是否校驗(yàn)敏感數(shù)據(jù)是否加密權(quán)限控制是否到位SQL注入是否防護(hù)跨站腳本是否過(guò)濾日志中是否泄露敏感信息安全性檢查的重要性怎么強(qiáng)調(diào)都不為過(guò)一個(gè)安全漏洞可能導(dǎo)致整個(gè)系統(tǒng)崩潰。我建議在評(píng)審清單中把安全性檢查單獨(dú)列出來(lái)并且標(biāo)記為“必須通過(guò)”級(jí)別。第三類是性能檢查。包括數(shù)據(jù)庫(kù)查詢是否高效循環(huán)中是否有重復(fù)計(jì)算內(nèi)存使用是否合理緩存策略是否恰當(dāng)網(wǎng)絡(luò)請(qǐng)求是否合并性能問(wèn)題往往在開發(fā)階段不容易發(fā)現(xiàn)等到上線后才發(fā)現(xiàn)就晚了。評(píng)審時(shí)重點(diǎn)關(guān)注那些可能成為性能瓶頸的代碼段比如嵌套循環(huán)、大量數(shù)據(jù)遍歷、頻繁的IO操作等。第四類是可讀性檢查。包括命名是否清晰注釋是否充分函數(shù)長(zhǎng)度是否合理代碼結(jié)構(gòu)是否清晰魔法數(shù)字是否提取可讀性檢查是最容易被忽視的但它的影響是長(zhǎng)期的。一段難以理解的代碼半年后可能連原作者都看不懂了。我建議把可讀性檢查的權(quán)重調(diào)高一些因?yàn)榇a是寫給人看的順便給機(jī)器執(zhí)行。第五類是測(cè)試檢查。包括單元測(cè)試是否覆蓋核心邏輯邊界條件是否測(cè)試異常路徑是否測(cè)試測(cè)試用例是否可維護(hù)測(cè)試檢查經(jīng)常被跳過(guò)理由是“時(shí)間不夠”。但根據(jù)我的經(jīng)驗(yàn)跳過(guò)測(cè)試檢查的代價(jià)往往更高因?yàn)楹笃谛迯?fù)bug的時(shí)間遠(yuǎn)超寫測(cè)試的時(shí)間。評(píng)審清單不是一成不變的需要定期迭代。我建議每個(gè)季度回顧一次評(píng)審清單把那些經(jīng)常被遺漏的檢查項(xiàng)加進(jìn)去把那些已經(jīng)形成習(xí)慣的檢查項(xiàng)簡(jiǎn)化掉。清單太長(zhǎng)會(huì)讓人望而生畏清單太短又起不到檢查作用找到平衡點(diǎn)很重要。3.2 評(píng)審意見(jiàn)的撰寫規(guī)范與溝通技巧評(píng)審意見(jiàn)的撰寫是一門藝術(shù)。同樣是指出一個(gè)問(wèn)題不同的表述方式會(huì)產(chǎn)生完全不同的效果。我見(jiàn)過(guò)太多因?yàn)樵u(píng)審意見(jiàn)措辭不當(dāng)而引發(fā)的團(tuán)隊(duì)矛盾了。下面分享幾個(gè)我總結(jié)的評(píng)審意見(jiàn)撰寫原則。原則一對(duì)事不對(duì)人。評(píng)審意見(jiàn)應(yīng)該針對(duì)代碼本身而不是針對(duì)代碼的作者。不要說(shuō)“你怎么又忘了處理空值”而要說(shuō)“這個(gè)變量在傳入空值時(shí)可能會(huì)導(dǎo)致異常建議增加空值檢查”。前者是指責(zé)后者是建議效果天差地別。原則二具體明確。評(píng)審意見(jiàn)要指出具體的問(wèn)題位置和具體的修改建議。不要說(shuō)“這里邏輯有問(wèn)題”而要說(shuō)“第45行的條件判斷在輸入為負(fù)數(shù)時(shí)會(huì)進(jìn)入錯(cuò)誤分支建議改為先判斷輸入是否大于零”。越具體的意見(jiàn)提交者越容易理解和執(zhí)行。原則三區(qū)分嚴(yán)重程度。不是所有問(wèn)題都同等重要。我建議把評(píng)審意見(jiàn)分成三個(gè)級(jí)別阻塞級(jí)、建議級(jí)、參考級(jí)。阻塞級(jí)是必須修改才能合并的問(wèn)題比如安全漏洞、邏輯錯(cuò)誤。建議級(jí)是推薦修改但不強(qiáng)制的問(wèn)題比如命名不夠清晰、注釋不夠充分。參考級(jí)是提供額外信息或思路的建議比如“這里可以考慮用另一種設(shè)計(jì)模式”。區(qū)分嚴(yán)重程度可以讓提交者知道哪些必須改、哪些可以商量。原則四提供正面反饋。評(píng)審不只是挑毛病也要肯定做得好的地方?？吹揭欢蝺?yōu)雅的實(shí)現(xiàn)、一個(gè)巧妙的算法、一處完善的測(cè)試不妨在評(píng)審意見(jiàn)中提一句“這段處理很清晰”“這個(gè)測(cè)試用例覆蓋得很全面”。正面反饋不僅能提升團(tuán)隊(duì)士氣還能強(qiáng)化好的編碼習(xí)慣。原則五控制情緒。評(píng)審過(guò)程中難免會(huì)遇到意見(jiàn)分歧。這時(shí)候最重要的是控制情緒不要讓技術(shù)討論升級(jí)為人身攻擊。如果發(fā)現(xiàn)討論開始變得情緒化建議暫停文字溝通改為面對(duì)面或視頻溝通。文字溝通容易產(chǎn)生誤解面對(duì)面溝通能快速消除歧義。提示評(píng)審意見(jiàn)中避免使用“顯然”“明顯”“當(dāng)然”這類詞這些詞會(huì)讓提交者覺(jué)得你在暗示他不夠聰明。用“建議”“可以考慮”“或許可以”這類中性詞替代。3.3 自動(dòng)化檢查與人工評(píng)審的分工“open-code-review”強(qiáng)調(diào)的一個(gè)核心理念是能自動(dòng)化的絕不人工檢查。人工評(píng)審的時(shí)間是寶貴的應(yīng)該用在自動(dòng)化工具無(wú)法判斷的地方比如設(shè)計(jì)合理性、業(yè)務(wù)邏輯正確性、代碼可維護(hù)性等。自動(dòng)化檢查應(yīng)該覆蓋哪些內(nèi)容我建議至少包括以下幾個(gè)方面。代碼格式化檢查確保團(tuán)隊(duì)代碼風(fēng)格統(tǒng)一。靜態(tài)代碼分析發(fā)現(xiàn)潛在的bug和代碼異味。測(cè)試覆蓋率檢查確保新增代碼有對(duì)應(yīng)的測(cè)試。依賴安全檢查發(fā)現(xiàn)已知的安全漏洞。構(gòu)建和測(cè)試執(zhí)行確保代碼能正常編譯和通過(guò)測(cè)試。這些自動(dòng)化檢查應(yīng)該在提交PR時(shí)自動(dòng)觸發(fā)檢查結(jié)果直接展示在PR頁(yè)面上。評(píng)審者只需要關(guān)注自動(dòng)化檢查無(wú)法覆蓋的部分。這樣做的好處是評(píng)審者不用再花時(shí)間糾結(jié)代碼風(fēng)格問(wèn)題可以把精力集中在更有價(jià)值的評(píng)審內(nèi)容上。但是要注意自動(dòng)化檢查不能設(shè)置得太嚴(yán)格。我見(jiàn)過(guò)有的團(tuán)隊(duì)把代碼風(fēng)格檢查設(shè)置成阻塞級(jí)結(jié)果開發(fā)者花大量時(shí)間在調(diào)整空格和換行上嚴(yán)重影響了開發(fā)效率。我的建議是代碼風(fēng)格檢查設(shè)置為建議級(jí)不阻塞合并流程但會(huì)在PR頁(yè)面上顯示警告。如果團(tuán)隊(duì)對(duì)代碼風(fēng)格有強(qiáng)制要求可以通過(guò)代碼格式化工具在提交前自動(dòng)修復(fù)而不是在評(píng)審階段卡住。人工評(píng)審應(yīng)該聚焦在哪些方面我認(rèn)為最重要的是設(shè)計(jì)合理性。自動(dòng)化工具可以檢查代碼是否符合語(yǔ)法規(guī)范但無(wú)法判斷設(shè)計(jì)是否合理。比如一個(gè)功能應(yīng)該拆分成幾個(gè)模塊模塊之間的依賴關(guān)系是否清晰接口設(shè)計(jì)是否易于擴(kuò)展這些問(wèn)題只有人工評(píng)審才能判斷。其次是業(yè)務(wù)邏輯正確性。自動(dòng)化測(cè)試可以覆蓋已知的測(cè)試用例但無(wú)法覆蓋所有業(yè)務(wù)場(chǎng)景。評(píng)審者需要根據(jù)自己對(duì)業(yè)務(wù)的理解判斷代碼是否實(shí)現(xiàn)了預(yù)期的業(yè)務(wù)邏輯是否考慮了各種邊界情況。最后是代碼可維護(hù)性。代碼不僅要能運(yùn)行還要易于理解和修改。評(píng)審者需要判斷代碼結(jié)構(gòu)是否清晰、命名是否合理、注釋是否充分、是否有過(guò)度設(shè)計(jì)或設(shè)計(jì)不足的問(wèn)題。4. 實(shí)操過(guò)程與核心環(huán)節(jié)實(shí)現(xiàn)4.1 從零搭建評(píng)審流程的完整步驟假設(shè)你現(xiàn)在要在一個(gè)團(tuán)隊(duì)里從零開始搭建代碼評(píng)審流程下面是我建議的完整步驟。這套流程我在多個(gè)團(tuán)隊(duì)里實(shí)踐過(guò)效果比較穩(wěn)定。第一步確定評(píng)審工具和平臺(tái)。首先確定使用哪個(gè)代碼托管平臺(tái)主流的平臺(tái)都支持PR機(jī)制。然后確定使用哪些輔助工具比如代碼格式化工具、靜態(tài)分析工具、測(cè)試覆蓋率工具。把這些工具集成到持續(xù)集成流水線中確保每次提交PR時(shí)自動(dòng)觸發(fā)檢查。第二步制定評(píng)審清單。根據(jù)團(tuán)隊(duì)的技術(shù)棧和業(yè)務(wù)特點(diǎn)制定一份評(píng)審清單。清單不要一開始就追求大而全先從最核心的檢查項(xiàng)開始比如正確性、安全性、測(cè)試覆蓋。等團(tuán)隊(duì)適應(yīng)了評(píng)審流程之后再逐步增加檢查項(xiàng)。第三步確定評(píng)審角色和職責(zé)。每個(gè)PR需要指定至少一個(gè)評(píng)審者。評(píng)審者可以是模塊的負(fù)責(zé)人也可以是對(duì)該模塊熟悉的開發(fā)者。如果PR涉及多個(gè)模塊可以指定多個(gè)評(píng)審者但要注意避免評(píng)審者過(guò)多導(dǎo)致溝通成本上升。我建議評(píng)審者數(shù)量控制在1到3人之間。第四步定義評(píng)審流程。明確從提交到合并的完整流程。我建議的流程是提交PR并填寫描述信息包括改動(dòng)目的、改動(dòng)內(nèi)容、測(cè)試情況。自動(dòng)化檢查觸發(fā)并展示結(jié)果。評(píng)審者收到通知后進(jìn)行評(píng)審提出評(píng)審意見(jiàn)。提交者根據(jù)評(píng)審意見(jiàn)進(jìn)行修改修改后重新觸發(fā)自動(dòng)化檢查。評(píng)審者確認(rèn)修改后批準(zhǔn)合并。合并到主分支。第五步建立評(píng)審模板。為PR描述和評(píng)審意見(jiàn)分別建立模板。PR描述模板包括改動(dòng)目的、改動(dòng)內(nèi)容、測(cè)試情況、影響范圍、相關(guān)issue鏈接。評(píng)審意見(jiàn)模板包括問(wèn)題描述、問(wèn)題位置、嚴(yán)重程度、建議方案。模板可以大大提升評(píng)審效率減少遺漏。第六步培訓(xùn)和推廣。新流程推行初期一定要做培訓(xùn)。培訓(xùn)內(nèi)容包括評(píng)審流程說(shuō)明、評(píng)審清單使用、評(píng)審意見(jiàn)撰寫規(guī)范、常見(jiàn)問(wèn)題處理。培訓(xùn)之后可以先在一個(gè)小范圍試點(diǎn)收集反饋后再全面推廣。第七步度量和優(yōu)化。流程運(yùn)行一段時(shí)間后需要收集數(shù)據(jù)來(lái)評(píng)估效果。關(guān)鍵指標(biāo)包括PR平均評(píng)審時(shí)長(zhǎng)、PR平均修改次數(shù)、評(píng)審意見(jiàn)數(shù)量、評(píng)審意見(jiàn)采納率、缺陷逃逸率。根據(jù)這些指標(biāo)找出流程中的瓶頸持續(xù)優(yōu)化。4.2 評(píng)審模板的具體內(nèi)容與使用示例評(píng)審模板是提升評(píng)審效率的利器。下面我分享一套經(jīng)過(guò)實(shí)踐檢驗(yàn)的模板你可以直接拿去用也可以根據(jù)團(tuán)隊(duì)情況調(diào)整。PR描述模板## 改動(dòng)目的 簡(jiǎn)要說(shuō)明這個(gè)PR要解決什么問(wèn)題或?qū)崿F(xiàn)什么功能。 ## 改動(dòng)內(nèi)容 列出主要的代碼改動(dòng)點(diǎn)包括新增文件、修改文件、刪除文件。 ## 測(cè)試情況 說(shuō)明做了哪些測(cè)試測(cè)試結(jié)果如何。包括單元測(cè)試、集成測(cè)試、手動(dòng)測(cè)試。 ## 影響范圍 說(shuō)明這個(gè)改動(dòng)可能影響哪些模塊或功能。 ## 相關(guān)鏈接 關(guān)聯(lián)的issue、設(shè)計(jì)文檔、需求文檔等。評(píng)審意見(jiàn)模板## 問(wèn)題描述 清晰描述發(fā)現(xiàn)的問(wèn)題。 ## 問(wèn)題位置 指出問(wèn)題所在的文件和行號(hào)。 ## 嚴(yán)重程度 阻塞級(jí) / 建議級(jí) / 參考級(jí) ## 建議方案 給出具體的修改建議或替代方案。 ## 參考示例 如果有參考代碼或文檔附上鏈接或代碼片段。使用模板的好處是顯而易見(jiàn)的。首先它確保評(píng)審者不會(huì)遺漏重要信息。其次它讓評(píng)審意見(jiàn)更加結(jié)構(gòu)化提交者更容易理解。最后它降低了評(píng)審的溝通成本因?yàn)殡p方都清楚信息的組織方式。但是要注意模板是工具不是枷鎖。不要為了填模板而填模板如果某個(gè)PR非常簡(jiǎn)單不需要填寫所有字段可以適當(dāng)簡(jiǎn)化。模板的目的是提升效率不是增加負(fù)擔(dān)。4.3 評(píng)審會(huì)議的組織與主持技巧除了異步的文字評(píng)審有時(shí)候也需要組織評(píng)審會(huì)議。評(píng)審會(huì)議適合討論復(fù)雜的設(shè)計(jì)方案、有爭(zhēng)議的技術(shù)選型、或者需要多方協(xié)調(diào)的改動(dòng)。但是評(píng)審會(huì)議不能濫用否則會(huì)變成時(shí)間黑洞。什么情況下應(yīng)該組織評(píng)審會(huì)議我建議在以下幾種情況下考慮PR涉及架構(gòu)級(jí)改動(dòng)影響多個(gè)模塊評(píng)審意見(jiàn)分歧較大文字溝通無(wú)法達(dá)成一致新人提交的PR需要詳細(xì)指導(dǎo)緊急修復(fù)需要快速?zèng)Q策。評(píng)審會(huì)議的組織有幾個(gè)關(guān)鍵點(diǎn)。第一提前準(zhǔn)備。會(huì)議組織者需要提前把PR鏈接、評(píng)審意見(jiàn)、討論要點(diǎn)發(fā)給參會(huì)者讓大家有足夠時(shí)間閱讀和思考。不要在會(huì)議上才第一次看代碼那樣效率極低。第二控制時(shí)長(zhǎng)。評(píng)審會(huì)議建議控制在30到45分鐘。超過(guò)這個(gè)時(shí)長(zhǎng)參會(huì)者的注意力會(huì)明顯下降。如果問(wèn)題較多可以拆分成多次會(huì)議或者把一些問(wèn)題轉(zhuǎn)為異步討論。第三明確主持人。評(píng)審會(huì)議需要有一個(gè)主持人來(lái)控制節(jié)奏、引導(dǎo)討論、記錄結(jié)論。主持人最好是技術(shù)負(fù)責(zé)人或資深開發(fā)者能夠快速判斷技術(shù)方案的可行性。第四聚焦關(guān)鍵問(wèn)題。評(píng)審會(huì)議不要逐行審查代碼那樣太浪費(fèi)時(shí)間。應(yīng)該聚焦在關(guān)鍵設(shè)計(jì)決策、有爭(zhēng)議的問(wèn)題、需要多方協(xié)調(diào)的事項(xiàng)上。具體的代碼細(xì)節(jié)可以在異步評(píng)審中處理。第五記錄結(jié)論。會(huì)議結(jié)束后主持人需要整理會(huì)議結(jié)論包括達(dá)成的共識(shí)、待辦事項(xiàng)、責(zé)任人、截止時(shí)間。結(jié)論要同步給所有參會(huì)者和相關(guān)人員確保信息一致。注意評(píng)審會(huì)議不是批斗會(huì)也不是表演會(huì)。它的目的是解決問(wèn)題不是展示誰(shuí)更聰明。主持人要營(yíng)造開放、平等的討論氛圍鼓勵(lì)所有人發(fā)表意見(jiàn)。5. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄5.1 評(píng)審效率低下的原因分析與改進(jìn)評(píng)審效率低是團(tuán)隊(duì)最常遇到的問(wèn)題。我總結(jié)了幾種典型情況以及對(duì)應(yīng)的改進(jìn)措施。情況一PR太大評(píng)審者看不完。這是最常見(jiàn)的問(wèn)題。一個(gè)PR包含幾十個(gè)文件的改動(dòng)評(píng)審者打開一看就頭疼最后只能草草瀏覽一遍。改進(jìn)措施是控制PR大小建議每個(gè)PR的代碼改動(dòng)控制在200到400行之間。如果改動(dòng)確實(shí)很大可以拆分成多個(gè)PR每個(gè)PR對(duì)應(yīng)一個(gè)獨(dú)立的功能點(diǎn)。情況二評(píng)審者太少成為瓶頸。如果團(tuán)隊(duì)只有一兩個(gè)人能評(píng)審代碼那這兩個(gè)人就會(huì)成為瓶頸PR排隊(duì)等待評(píng)審的時(shí)間會(huì)很長(zhǎng)。改進(jìn)措施是擴(kuò)大評(píng)審者隊(duì)伍讓更多開發(fā)者參與評(píng)審?？梢越⒃u(píng)審輪值制度每周指定不同的評(píng)審者。同時(shí)通過(guò)評(píng)審培訓(xùn)提升團(tuán)隊(duì)整體的評(píng)審能力。情況三評(píng)審意見(jiàn)不明確來(lái)回溝通耗時(shí)。如果評(píng)審意見(jiàn)寫得模糊提交者需要反復(fù)詢問(wèn)才能理解溝通成本很高。改進(jìn)措施是使用評(píng)審意見(jiàn)模板強(qiáng)制要求評(píng)審者提供具體的問(wèn)題描述和建議方案。同時(shí)鼓勵(lì)評(píng)審者在提出意見(jiàn)時(shí)附上參考代碼或文檔鏈接。情況四自動(dòng)化檢查太慢阻塞評(píng)審流程。如果自動(dòng)化檢查需要跑十幾分鐘甚至更久評(píng)審者等待檢查結(jié)果的時(shí)間就會(huì)很長(zhǎng)。改進(jìn)措施是優(yōu)化自動(dòng)化檢查流程把檢查分成快速檢查和完整檢查兩級(jí)?？焖贆z查在提交時(shí)立即執(zhí)行只包含最核心的檢查項(xiàng)。完整檢查在后臺(tái)異步執(zhí)行檢查結(jié)果出來(lái)后通知評(píng)審者。情況五評(píng)審標(biāo)準(zhǔn)不統(tǒng)一評(píng)審者之間意見(jiàn)沖突。如果團(tuán)隊(duì)沒(méi)有統(tǒng)一的評(píng)審標(biāo)準(zhǔn)不同的評(píng)審者可能會(huì)提出相互矛盾的意見(jiàn)。改進(jìn)措施是制定評(píng)審清單明確哪些是必須檢查的項(xiàng)、哪些是建議檢查的項(xiàng)。同時(shí)定期組織評(píng)審校準(zhǔn)會(huì)議讓評(píng)審者討論有爭(zhēng)議的評(píng)審案例統(tǒng)一評(píng)審標(biāo)準(zhǔn)。5.2 評(píng)審意見(jiàn)沖突的處理策略評(píng)審意見(jiàn)沖突是難免的。不同的評(píng)審者可能有不同的技術(shù)觀點(diǎn)提交者也可能不認(rèn)同評(píng)審者的意見(jiàn)。如何處理這些沖突直接影響團(tuán)隊(duì)的協(xié)作氛圍。策略一用數(shù)據(jù)說(shuō)話。如果沖突是關(guān)于性能的可以跑基準(zhǔn)測(cè)試來(lái)對(duì)比不同方案的性能差異。如果沖突是關(guān)于可讀性的可以找?guī)讉€(gè)不了解上下文的開發(fā)者來(lái)試讀代碼看哪個(gè)方案更容易理解。數(shù)據(jù)比觀點(diǎn)更有說(shuō)服力。策略二升級(jí)決策。如果評(píng)審者和提交者無(wú)法達(dá)成一致可以把問(wèn)題升級(jí)給技術(shù)負(fù)責(zé)人或架構(gòu)師來(lái)決策。升級(jí)決策不是誰(shuí)對(duì)誰(shuí)錯(cuò)的問(wèn)題而是需要一個(gè)有權(quán)限的人來(lái)拍板讓事情繼續(xù)推進(jìn)。策略三先合并后優(yōu)化。如果沖突不是阻塞級(jí)的可以先按照提交者的方案合并然后在后續(xù)的迭代中優(yōu)化。不要因?yàn)橐粋€(gè)非關(guān)鍵問(wèn)題卡住整個(gè)流程?？梢栽诖a中留下TODO注釋提醒后續(xù)優(yōu)化。策略四建立決策記錄。對(duì)于有爭(zhēng)議的技術(shù)決策建議建立決策記錄文檔。記錄內(nèi)容包括決策背景、可選方案、最終選擇、選擇理由、決策人、決策時(shí)間。這樣后續(xù)遇到類似問(wèn)題時(shí)可以查閱歷史決策避免重復(fù)討論。策略五對(duì)事不對(duì)人。無(wú)論沖突多么激烈都要保持對(duì)事不對(duì)人的原則。技術(shù)討論應(yīng)該聚焦在技術(shù)方案本身而不是誰(shuí)的技術(shù)水平更高。主持人要及時(shí)制止人身攻擊或情緒化表達(dá)。5.3 評(píng)審流程的度量與持續(xù)優(yōu)化評(píng)審流程不是一成不變的需要持續(xù)度量和優(yōu)化。下面是我建議關(guān)注的幾個(gè)關(guān)鍵指標(biāo)以及對(duì)應(yīng)的優(yōu)化方向。指標(biāo)名稱指標(biāo)說(shuō)明健康范圍優(yōu)化方向PR平均評(píng)審時(shí)長(zhǎng)從提交PR到獲得第一次評(píng)審意見(jiàn)的時(shí)間4小時(shí)以內(nèi)增加評(píng)審者、設(shè)置評(píng)審提醒PR平均合并時(shí)長(zhǎng)從提交PR到合并到主分支的時(shí)間24小時(shí)以內(nèi)簡(jiǎn)化流程、減少阻塞級(jí)意見(jiàn)PR平均修改次數(shù)一個(gè)PR從提交到合并經(jīng)歷的修改輪次2到3次提升PR描述質(zhì)量、明確評(píng)審標(biāo)準(zhǔn)評(píng)審意見(jiàn)采納率評(píng)審意見(jiàn)被提交者采納的比例70%以上提升評(píng)審意見(jiàn)質(zhì)量、加強(qiáng)溝通缺陷逃逸率合并后發(fā)現(xiàn)的缺陷占全部缺陷的比例10%以下加強(qiáng)測(cè)試檢查、完善評(píng)審清單評(píng)審者參與度每個(gè)評(píng)審者平均每周評(píng)審的PR數(shù)量3到5個(gè)評(píng)審輪值、評(píng)審培訓(xùn)這些指標(biāo)不是用來(lái)考核個(gè)人的而是用來(lái)評(píng)估流程健康度的。如果某個(gè)指標(biāo)偏離健康范圍需要分析原因并采取改進(jìn)措施。比如PR平均評(píng)審時(shí)長(zhǎng)過(guò)長(zhǎng)可能是評(píng)審者太少或者評(píng)審提醒不及時(shí)。PR平均修改次數(shù)過(guò)多可能是PR描述不夠清晰或者評(píng)審標(biāo)準(zhǔn)不明確。度量數(shù)據(jù)的收集可以通過(guò)代碼托管平臺(tái)的API自動(dòng)獲取也可以手動(dòng)統(tǒng)計(jì)。建議每月回顧一次度量數(shù)據(jù)每季度做一次流程優(yōu)化。優(yōu)化措施要小步快跑一次只調(diào)整一兩個(gè)點(diǎn)觀察效果后再繼續(xù)調(diào)整。提示不要過(guò)度追求指標(biāo)好看。評(píng)審流程的最終目標(biāo)是提升代碼質(zhì)量而不是讓指標(biāo)漂亮。如果為了縮短評(píng)審時(shí)長(zhǎng)而草草評(píng)審反而會(huì)埋下質(zhì)量隱患。6. 開放協(xié)作場(chǎng)景下的特殊考量6.1 跨團(tuán)隊(duì)協(xié)作的評(píng)審協(xié)調(diào)當(dāng)項(xiàng)目涉及多個(gè)團(tuán)隊(duì)協(xié)作時(shí)代碼評(píng)審的復(fù)雜度會(huì)顯著上升。不同團(tuán)隊(duì)可能有不同的技術(shù)棧、不同的編碼規(guī)范、不同的評(píng)審習(xí)慣。如何協(xié)調(diào)這些差異是“open-code-review”需要解決的重要問(wèn)題。第一建立跨團(tuán)隊(duì)評(píng)審協(xié)議。在項(xiàng)目啟動(dòng)階段各團(tuán)隊(duì)就應(yīng)該坐下來(lái)討論評(píng)審協(xié)議。協(xié)議內(nèi)容包括使用哪個(gè)代碼托管平臺(tái)、采用什么評(píng)審流程、遵循什么評(píng)審標(biāo)準(zhǔn)、如何處理評(píng)審沖突。協(xié)議一旦確定各團(tuán)隊(duì)都要遵守不能各自為政。第二指定接口人。每個(gè)團(tuán)隊(duì)指定一個(gè)接口人負(fù)責(zé)協(xié)調(diào)跨團(tuán)隊(duì)的評(píng)審事宜。接口人的職責(zé)包括接收其他團(tuán)隊(duì)的評(píng)審請(qǐng)求、分配評(píng)審任務(wù)、跟蹤評(píng)審進(jìn)度、協(xié)調(diào)評(píng)審沖突。接口人是跨團(tuán)隊(duì)溝通的橋梁能夠大大降低溝通成本。第三統(tǒng)一評(píng)審工具鏈?？鐖F(tuán)隊(duì)協(xié)作時(shí)工具鏈的統(tǒng)一尤為重要。如果A團(tuán)隊(duì)用一套靜態(tài)分析工具B團(tuán)隊(duì)用另一套檢查結(jié)果就無(wú)法對(duì)比。建議在項(xiàng)目層面統(tǒng)一工具鏈包括代碼格式化工具、靜態(tài)分析工具、測(cè)試框架、持續(xù)集成平臺(tái)。第四建立共享的評(píng)審知識(shí)庫(kù)。把評(píng)審過(guò)程中發(fā)現(xiàn)的問(wèn)題、總結(jié)的經(jīng)驗(yàn)、制定的規(guī)范都記錄在共享知識(shí)庫(kù)中。這樣各團(tuán)隊(duì)的評(píng)審者可以互相學(xué)習(xí)避免重復(fù)踩坑。知識(shí)庫(kù)可以是一個(gè)文檔倉(cāng)庫(kù)也可以是一個(gè)內(nèi)部Wiki。第五定期組織跨團(tuán)隊(duì)評(píng)審交流會(huì)。每個(gè)季度組織一次跨團(tuán)隊(duì)的評(píng)審交流會(huì)分享各團(tuán)隊(duì)的評(píng)審實(shí)踐、討論遇到的共性問(wèn)題、協(xié)調(diào)評(píng)審標(biāo)準(zhǔn)的差異。這種交流會(huì)不僅能解決具體問(wèn)題還能增進(jìn)團(tuán)隊(duì)之間的了解和信任。6.2 開源社區(qū)貢獻(xiàn)的評(píng)審特點(diǎn)開源社區(qū)的代碼評(píng)審跟公司內(nèi)部有很大不同。在開源社區(qū)提交者來(lái)自世界各地技術(shù)背景各異溝通方式也不同。評(píng)審者需要更加注意溝通方式和文化差異。特點(diǎn)一提交者水平參差不齊。開源社區(qū)的貢獻(xiàn)者可能是資深開發(fā)者也可能是剛?cè)腴T的新手。評(píng)審者需要根據(jù)提交者的水平調(diào)整評(píng)審意見(jiàn)的詳細(xì)程度。對(duì)于新手要給出更詳細(xì)的指導(dǎo)甚至提供示例代碼。對(duì)于資深開發(fā)者可以更簡(jiǎn)潔地指出問(wèn)題。特點(diǎn)二溝通語(yǔ)言可能不同。開源社區(qū)的通用語(yǔ)言是英語(yǔ)但很多貢獻(xiàn)者的母語(yǔ)不是英語(yǔ)。評(píng)審者在撰寫評(píng)審意見(jiàn)時(shí)要使用簡(jiǎn)單清晰的英語(yǔ)避免使用俚語(yǔ)、縮寫、文化特定的表達(dá)。如果發(fā)現(xiàn)溝通有困難可以嘗試用圖示或代碼示例來(lái)輔助說(shuō)明。特點(diǎn)三響應(yīng)時(shí)間不確定。開源社區(qū)的貢獻(xiàn)者都是志愿者響應(yīng)時(shí)間可能很長(zhǎng)。評(píng)審者需要耐心等待不要因?yàn)樘峤徽邘滋鞗](méi)回復(fù)就關(guān)閉PR。同時(shí)評(píng)審者自己也要及時(shí)響應(yīng)不要讓PR長(zhǎng)時(shí)間無(wú)人處理。特點(diǎn)四評(píng)審標(biāo)準(zhǔn)需要公開透明。開源項(xiàng)目的評(píng)審標(biāo)準(zhǔn)應(yīng)該公開在項(xiàng)目文檔中讓所有貢獻(xiàn)者都能提前了解。評(píng)審標(biāo)準(zhǔn)包括代碼風(fēng)格要求、測(cè)試要求、文檔要求、提交信息格式要求等。公開透明的標(biāo)準(zhǔn)可以減少評(píng)審爭(zhēng)議提升評(píng)審效率。特點(diǎn)五注重知識(shí)傳遞。開源社區(qū)的評(píng)審不僅是審查代碼更是傳遞知識(shí)。評(píng)審者應(yīng)該在評(píng)審意見(jiàn)中解釋為什么這樣寫更好而不僅僅是指出問(wèn)題。這樣可以幫助貢獻(xiàn)者成長(zhǎng)也能提升整個(gè)社區(qū)的技術(shù)水平。6.3 評(píng)審文化的建設(shè)與維護(hù)評(píng)審文化是“open-code-review”能否成功落地的關(guān)鍵。沒(méi)有好的評(píng)審文化再好的流程和工具也發(fā)揮不了作用。評(píng)審文化的建設(shè)需要從以下幾個(gè)方面入手。第一領(lǐng)導(dǎo)層以身作則。技術(shù)負(fù)責(zé)人和資深開發(fā)者要帶頭參與評(píng)審認(rèn)真撰寫評(píng)審意見(jiàn)積極回應(yīng)評(píng)審意見(jiàn)。如果領(lǐng)導(dǎo)層把評(píng)審當(dāng)成負(fù)擔(dān)敷衍了事整個(gè)團(tuán)隊(duì)都會(huì)效仿。第二鼓勵(lì)學(xué)習(xí)而非指責(zé)。評(píng)審的目的是學(xué)習(xí)和改進(jìn)不是指責(zé)和懲罰。評(píng)審意見(jiàn)應(yīng)該以建設(shè)性的方式提出幫助提交者提升代碼質(zhì)量。對(duì)于反復(fù)出現(xiàn)的問(wèn)題應(yīng)該通過(guò)培訓(xùn)和文檔來(lái)改進(jìn)而不是通過(guò)批評(píng)來(lái)施壓。第三保護(hù)新人的積極性。新人提交的代碼往往問(wèn)題較多評(píng)審者要注意溝通方式不要打擊新人的積極性?？梢韵瓤隙ㄗ龅煤玫牡胤皆僦赋鲂枰倪M(jìn)的地方。對(duì)于簡(jiǎn)單的問(wèn)題可以私下溝通避免在公開評(píng)審中讓新人難堪。第四定期回顧評(píng)審實(shí)踐。每個(gè)季度組織一次評(píng)審回顧討論評(píng)審流程中存在的問(wèn)題、收集團(tuán)隊(duì)成員的反饋、制定改進(jìn)措施?；仡檿?huì)議要營(yíng)造開放的氛圍鼓勵(lì)大家說(shuō)出真實(shí)想法。第五慶祝評(píng)審成果。當(dāng)團(tuán)隊(duì)通過(guò)評(píng)審發(fā)現(xiàn)并修復(fù)了重要缺陷時(shí)應(yīng)該公開表?yè)P(yáng)。當(dāng)評(píng)審者提出了高質(zhì)量的評(píng)審意見(jiàn)時(shí)也應(yīng)該給予認(rèn)可。這樣可以強(qiáng)化評(píng)審的價(jià)值感讓更多人愿意投入評(píng)審工作。注意評(píng)審文化的建設(shè)是一個(gè)長(zhǎng)期過(guò)程不可能一蹴而就。團(tuán)隊(duì)負(fù)責(zé)人要有耐心持續(xù)投入逐步培養(yǎng)。不要指望發(fā)一個(gè)通知就能改變團(tuán)隊(duì)文化。7. 工具鏈集成與自動(dòng)化實(shí)踐7.1 持續(xù)集成流水線的配置要點(diǎn)持續(xù)集成流水線是“open-code-review”的基礎(chǔ)設(shè)施。沒(méi)有持續(xù)集成自動(dòng)化檢查就無(wú)從談起。下面我分享一些配置持續(xù)集成流水線的要點(diǎn)。要點(diǎn)一分階段執(zhí)行檢查。不要把所有的檢查都放在一個(gè)階段執(zhí)行。建議分成三個(gè)階段快速檢查、完整檢查、部署檢查?？焖贆z查在提交時(shí)立即執(zhí)行包括代碼格式檢查、靜態(tài)分析、單元測(cè)試。完整檢查在快速檢查通過(guò)后執(zhí)行包括集成測(cè)試、端到端測(cè)試、性能測(cè)試。部署檢查在合并到主分支后執(zhí)行包括構(gòu)建鏡像、部署到測(cè)試環(huán)境、冒煙測(cè)試。要點(diǎn)二并行執(zhí)行獨(dú)立檢查。如果多個(gè)檢查之間沒(méi)有依賴關(guān)系可以并行執(zhí)行縮短整體檢查時(shí)間。比如代碼格式檢查和靜態(tài)分析可以并行單元測(cè)試和集成測(cè)試可以并行。大多數(shù)持續(xù)集成平臺(tái)都支持并行任務(wù)配置。要點(diǎn)三緩存依賴和構(gòu)建產(chǎn)物。依賴下載和構(gòu)建編譯往往耗時(shí)較長(zhǎng)。配置緩存可以顯著縮短檢查時(shí)間。比如緩存包管理器的依賴目錄、緩存編譯中間產(chǎn)物。大多數(shù)持續(xù)集成平臺(tái)都提供緩存機(jī)制配置起來(lái)也不復(fù)雜。要點(diǎn)四設(shè)置合理的超時(shí)時(shí)間。檢查任務(wù)不能無(wú)限期運(yùn)行。建議為每個(gè)檢查任務(wù)設(shè)置超時(shí)時(shí)間超時(shí)后自動(dòng)終止并標(biāo)記為失敗。超時(shí)時(shí)間根據(jù)檢查類型設(shè)置快速檢查建議5分鐘完整檢查建議30分鐘部署檢查建議60分鐘。要點(diǎn)五失敗時(shí)提供清晰的錯(cuò)誤信息。檢查失敗時(shí)流水線應(yīng)該輸出清晰的錯(cuò)誤信息告訴開發(fā)者哪個(gè)檢查失敗了、失敗原因是什么、如何修復(fù)。錯(cuò)誤信息越清晰開發(fā)者修復(fù)問(wèn)題的速度越快。7.2 靜態(tài)分析工具的選型與配置靜態(tài)分析工具是自動(dòng)化檢查的重要組成部分。它可以在不運(yùn)行代碼的情況下發(fā)現(xiàn)潛在的問(wèn)題。下面我分享一些靜態(tài)分析工具的選型建議和配置要點(diǎn)。選型原則一匹配技術(shù)棧。不同的編程語(yǔ)言有不同的靜態(tài)分析工具。選擇時(shí)要確保工具支持團(tuán)隊(duì)使用的編程語(yǔ)言和框架。比如Java生態(tài)有SpotBugs、PMD、CheckstyleJavaScript生態(tài)有ESLint、TypeScript ESLintPython生態(tài)有Pylint、Flake8、Mypy。選型原則二規(guī)則可配置。不同的團(tuán)隊(duì)有不同的編碼規(guī)范。靜態(tài)分析工具的規(guī)則應(yīng)該可以配置允許團(tuán)隊(duì)啟用或禁用特定規(guī)則調(diào)整規(guī)則的嚴(yán)重程度。不要選擇規(guī)則不可配置的工具那樣會(huì)很難適應(yīng)團(tuán)隊(duì)的實(shí)際需求。選型原則三誤報(bào)率低。靜態(tài)分析工具最大的問(wèn)題是誤報(bào)。如果誤報(bào)太多開發(fā)者就會(huì)忽略所有警告工具就失去了意義。選擇誤報(bào)率低的工具或者通過(guò)配置減少誤報(bào)。對(duì)于確實(shí)無(wú)法避免的誤報(bào)可以通過(guò)注釋來(lái)抑制特定警告。配置要點(diǎn)一分級(jí)設(shè)置規(guī)則。把規(guī)則分成錯(cuò)誤、警告、提示三個(gè)級(jí)別。錯(cuò)誤級(jí)別是必須修復(fù)的問(wèn)題比如空指針引用、資源泄露。警告級(jí)別是建議修復(fù)的問(wèn)題比如未使用的變量、過(guò)長(zhǎng)的函數(shù)。提示級(jí)別是參考信息比如可以簡(jiǎn)化的表達(dá)式。不同級(jí)別的規(guī)則在流水線中有不同的處理方式。配置要點(diǎn)二增量檢查。對(duì)于大型項(xiàng)目全量靜態(tài)分析可能耗時(shí)很長(zhǎng)。可以配置增量檢查只分析本次改動(dòng)涉及的文件。大多數(shù)靜態(tài)分析工具都支持增量檢查模式。配置要點(diǎn)三定期更新規(guī)則。靜態(tài)分析工具的規(guī)則庫(kù)會(huì)不斷更新新的規(guī)則可以發(fā)現(xiàn)新的問(wèn)題類型。建議定期更新工具版本和規(guī)則庫(kù)但要注意新規(guī)則可能會(huì)引入新的誤報(bào)更新后需要觀察一段時(shí)間。7.3 評(píng)審數(shù)據(jù)的收集與分析評(píng)審數(shù)據(jù)的收集和分析可以幫助團(tuán)隊(duì)了解評(píng)審流程的運(yùn)行狀況發(fā)現(xiàn)改進(jìn)機(jī)會(huì)。下面我分享一些數(shù)據(jù)收集和分析的實(shí)踐。數(shù)據(jù)收集方式一平臺(tái)API。大多數(shù)代碼托管平臺(tái)都提供API可以獲取PR的詳細(xì)信息包括提交時(shí)間、評(píng)審時(shí)間、合并時(shí)間、評(píng)審意見(jiàn)數(shù)量、修改次數(shù)等。通過(guò)API定期拉取數(shù)據(jù)存儲(chǔ)到數(shù)據(jù)庫(kù)中便于后續(xù)分析。數(shù)據(jù)收集方式二Webhook。代碼托管平臺(tái)支持Webhook可以在PR狀態(tài)變化時(shí)推送事件通知。通過(guò)Webhook可以實(shí)時(shí)收集評(píng)審數(shù)據(jù)及時(shí)發(fā)現(xiàn)問(wèn)題。比如當(dāng)PR超過(guò)24小時(shí)未評(píng)審時(shí)自動(dòng)發(fā)送提醒。數(shù)據(jù)收集方式三手動(dòng)記錄。有些數(shù)據(jù)無(wú)法通過(guò)API自動(dòng)獲取比如評(píng)審意見(jiàn)的采納情況、評(píng)審會(huì)議的結(jié)論等。這些數(shù)據(jù)可以通過(guò)手動(dòng)記錄的方式收集。建議使用簡(jiǎn)單的表格工具記錄不要搞得太復(fù)雜。數(shù)據(jù)分析維度一時(shí)間維度。分析PR評(píng)審時(shí)長(zhǎng)、合并時(shí)長(zhǎng)隨時(shí)間的變化趨勢(shì)。如果發(fā)現(xiàn)評(píng)審時(shí)長(zhǎng)在某個(gè)時(shí)間段明顯上升可能是評(píng)審者人手不足或者PR數(shù)量激增。數(shù)據(jù)分析維度二人員維度。分析每個(gè)評(píng)審者的評(píng)審數(shù)量、評(píng)審質(zhì)量、響應(yīng)速度。注意不要用這些數(shù)據(jù)來(lái)考核個(gè)人而是用來(lái)發(fā)現(xiàn)流程問(wèn)題。比如某個(gè)評(píng)審者的評(píng)審數(shù)量明顯高于其他人可能是評(píng)審任務(wù)分配不均。數(shù)據(jù)分析維度三質(zhì)量維度。分析評(píng)審意見(jiàn)的數(shù)量、類型、采納率。如果評(píng)審意見(jiàn)數(shù)量很少可能是評(píng)審者不夠認(rèn)真或者PR質(zhì)量很高。如果評(píng)審意見(jiàn)采納率很低可能是評(píng)審意見(jiàn)質(zhì)量不高或者提交者不配合。數(shù)據(jù)分析維度四缺陷維度。分析合并后發(fā)現(xiàn)的缺陷與評(píng)審過(guò)程的關(guān)系。如果很多缺陷在評(píng)審中沒(méi)有被發(fā)現(xiàn)說(shuō)明評(píng)審清單需要完善或者評(píng)審者需要培訓(xùn)。提示數(shù)據(jù)分析的目的是改進(jìn)流程不是考核個(gè)人。在使用評(píng)審數(shù)據(jù)時(shí)要注意保護(hù)個(gè)人隱私避免造成不必要的壓力。8. 從評(píng)審到知識(shí)沉淀的閉環(huán)8.1 評(píng)審經(jīng)驗(yàn)的文檔化與復(fù)用代碼評(píng)審過(guò)程中產(chǎn)生的經(jīng)驗(yàn)和知識(shí)如果不加以整理和沉淀就會(huì)隨著時(shí)間流逝而消失。把評(píng)審經(jīng)驗(yàn)文檔化是“open-code-review”的重要環(huán)節(jié)。文檔化的內(nèi)容一常見(jiàn)問(wèn)題清單。把評(píng)審中反復(fù)出現(xiàn)的問(wèn)題整理成清單包括問(wèn)題描述、問(wèn)題示例、修復(fù)方法。這份清單可以作為新人的學(xué)習(xí)材料也可以作為評(píng)審者的檢查參考。常見(jiàn)問(wèn)題清單應(yīng)該定期更新把新發(fā)現(xiàn)的問(wèn)題加進(jìn)去。文檔化的內(nèi)容二最佳實(shí)踐案例。把評(píng)審中發(fā)現(xiàn)的優(yōu)秀代碼實(shí)現(xiàn)整理成案例包括代碼片段、設(shè)計(jì)思路、適用場(chǎng)景。這些案例可以作為團(tuán)隊(duì)的學(xué)習(xí)資料幫助開發(fā)者提升編碼水平。最佳實(shí)踐案例應(yīng)該分類整理比如性能優(yōu)化案例、安全編碼案例、可讀性提升案例。文檔化的內(nèi)容三評(píng)審決策記錄。把評(píng)審中做出的重要技術(shù)決策記錄下來(lái)包括決策背景、可選方案、最終選擇、選擇理由。這些決策記錄可以幫助后續(xù)遇到類似問(wèn)題時(shí)快速參考避免重復(fù)討論。文檔化的內(nèi)容四評(píng)審培訓(xùn)材料。把評(píng)審流程、評(píng)審標(biāo)準(zhǔn)、評(píng)審技巧整理成培訓(xùn)材料用于新評(píng)審者的培訓(xùn)。培訓(xùn)材料應(yīng)該包括理論講解、案例分析、實(shí)操練習(xí)。培訓(xùn)材料要定期更新反映最新的評(píng)審實(shí)踐。文檔化的關(guān)鍵是易于檢索和復(fù)用。建議使用支持全文搜索的文檔平臺(tái)把文檔分類整理添加標(biāo)簽和索引。同時(shí)要建立文檔更新機(jī)制指定專人負(fù)責(zé)文檔維護(hù)確保文檔內(nèi)容不過(guò)時(shí)。8.2 評(píng)審與代碼規(guī)范的聯(lián)動(dòng)代碼評(píng)審和代碼規(guī)范是相輔相成的。代碼規(guī)范為評(píng)審提供了標(biāo)準(zhǔn)評(píng)審為代碼規(guī)范的完善提供了反饋。把兩者聯(lián)動(dòng)起來(lái)可以形成良性循環(huán)。聯(lián)動(dòng)方式一評(píng)審中發(fā)現(xiàn)規(guī)范缺失。如果評(píng)審中反復(fù)發(fā)現(xiàn)某一類問(wèn)題但代碼規(guī)范中沒(méi)有相關(guān)規(guī)定說(shuō)明規(guī)范需要補(bǔ)充。比如評(píng)審中多次發(fā)現(xiàn)日志打印不規(guī)范的問(wèn)題就應(yīng)該在代碼規(guī)范中增加日志打印的規(guī)范。聯(lián)動(dòng)方式二規(guī)范更新后同步評(píng)審清單。代碼規(guī)范更新后評(píng)審清單也要相應(yīng)更新。確保評(píng)審者按照最新的規(guī)范進(jìn)行評(píng)審。同時(shí)要把規(guī)范更新的內(nèi)容通知給所有開發(fā)者讓大家了解新的要求。聯(lián)動(dòng)方式三自動(dòng)化檢查規(guī)則與規(guī)范同步。代碼規(guī)范中能夠自動(dòng)檢查的規(guī)則應(yīng)該同步到自動(dòng)化檢查工具中。這樣規(guī)范就不僅僅是文檔而是可執(zhí)行的檢查項(xiàng)。自動(dòng)化檢查可以確保規(guī)范得到持續(xù)執(zhí)行不依賴人工記憶。聯(lián)動(dòng)方式四定期回顧規(guī)范執(zhí)行情況。定期回顧代碼規(guī)范的執(zhí)行情況分析哪些規(guī)范執(zhí)行得好、哪些規(guī)范執(zhí)行得差。對(duì)于執(zhí)行得差的規(guī)范要分析原因是規(guī)范本身不合理還是開發(fā)者不知道還是檢查不到位。根據(jù)分析結(jié)果采取改進(jìn)措施。8.3 評(píng)審能力的持續(xù)提升路徑評(píng)審能力不是天生的需要持續(xù)學(xué)習(xí)和練習(xí)。下面我分享一條評(píng)審能力的提升路徑供參考。階段一學(xué)習(xí)基礎(chǔ)知識(shí)。新手評(píng)審者需要先學(xué)習(xí)代碼評(píng)審的基礎(chǔ)知識(shí)包括評(píng)審流程、評(píng)審標(biāo)準(zhǔn)、評(píng)審意見(jiàn)撰寫規(guī)范?？梢酝ㄟ^(guò)閱讀文檔、參加培訓(xùn)、觀摩資深評(píng)審者的評(píng)審過(guò)程來(lái)學(xué)習(xí)。階段二在指導(dǎo)下評(píng)審。新手評(píng)審者在資深評(píng)審者的指導(dǎo)下進(jìn)行評(píng)審?？梢韵仍u(píng)審簡(jiǎn)單的PR資深評(píng)審者復(fù)核評(píng)審意見(jiàn)指出不足之處。這個(gè)階段的目標(biāo)是熟悉評(píng)審流程掌握評(píng)審的基本方法。階段三獨(dú)立評(píng)審。新手評(píng)審者可以獨(dú)立評(píng)審PR但評(píng)審意見(jiàn)需要資深評(píng)審者確認(rèn)后才能發(fā)送。這個(gè)階段的目標(biāo)是提升評(píng)審的準(zhǔn)確性和全面性減少遺漏和誤判。階段四獨(dú)立評(píng)審并指導(dǎo)他人。評(píng)審者可以獨(dú)立評(píng)審并發(fā)送評(píng)審意見(jiàn)同時(shí)開始指導(dǎo)新的評(píng)審者。這個(gè)階段的目標(biāo)是提升評(píng)審效率形成自己的評(píng)審風(fēng)格。階段五評(píng)審專家。評(píng)審者成為團(tuán)隊(duì)的評(píng)審專家能夠處理復(fù)雜的評(píng)審案例解決評(píng)審爭(zhēng)議制定評(píng)審標(biāo)準(zhǔn)。這個(gè)階段的目標(biāo)是推動(dòng)團(tuán)隊(duì)評(píng)審文化的建設(shè)提升團(tuán)隊(duì)整體的評(píng)審水平。每個(gè)階段的時(shí)間長(zhǎng)短因人而異取決于個(gè)人的技術(shù)基礎(chǔ)、學(xué)習(xí)能力和投入時(shí)間。重要的是保持持續(xù)學(xué)習(xí)的態(tài)度不斷反思和總結(jié)自己的評(píng)審實(shí)踐。提示評(píng)審能力的提升不僅靠評(píng)審實(shí)踐還要靠編碼實(shí)踐。一個(gè)優(yōu)秀的評(píng)審者首先是一個(gè)優(yōu)秀的編碼者。只有自己寫過(guò)足夠多的代碼才能理解代碼中的各種問(wèn)題和權(quán)衡。9. 我個(gè)人的實(shí)操體會(huì)聊了這么多流程和方法最后分享幾點(diǎn)我個(gè)人的實(shí)操體會(huì)。這些體會(huì)都是從實(shí)際項(xiàng)目中摸爬滾打出來(lái)的有些甚至是用教訓(xùn)換來(lái)的。體會(huì)一評(píng)審流程要簡(jiǎn)單。我見(jiàn)過(guò)太多團(tuán)隊(duì)把評(píng)審流程搞得太復(fù)雜又是評(píng)審委員會(huì)又是多級(jí)審批結(jié)果流程本身成了負(fù)擔(dān)。評(píng)審流程應(yīng)該盡量簡(jiǎn)單能自動(dòng)化的自動(dòng)化能異步的異步能一個(gè)人決策的就不要三個(gè)人討論。流程越簡(jiǎn)單執(zhí)行越到位。體會(huì)二評(píng)審標(biāo)準(zhǔn)要統(tǒng)一。評(píng)審標(biāo)準(zhǔn)不統(tǒng)一是團(tuán)隊(duì)矛盾的常見(jiàn)來(lái)源。同一個(gè)問(wèn)題A評(píng)審者說(shuō)必須改B評(píng)審者說(shuō)無(wú)所謂提交者就懵了。解決方法是制定明確的評(píng)審清單并且定期校準(zhǔn)評(píng)審標(biāo)準(zhǔn)。評(píng)審清單要具體、可操作不要寫“代碼要清晰”這種模糊的要求要寫“函數(shù)長(zhǎng)度不超過(guò)50行”這種可檢查的標(biāo)準(zhǔn)。體會(huì)三評(píng)審意見(jiàn)要具體?！斑@里改一下”是最無(wú)效的評(píng)審意見(jiàn)。評(píng)審意見(jiàn)要具體到問(wèn)題位置、問(wèn)題描述、建議方案。如果可能的話附上參考代碼或文檔鏈接。具體的評(píng)審意見(jiàn)不僅能幫助提交者快速理解問(wèn)題還能減少來(lái)回溝通的成本。體會(huì)四評(píng)審文化要開放。評(píng)審不是挑刺是協(xié)作。評(píng)審者要抱著幫助提交者提升的心態(tài)提交者要抱著學(xué)習(xí)的心態(tài)。雙方都要對(duì)事不對(duì)人聚焦在代碼本身而不是誰(shuí)的技術(shù)水平更高。開放的評(píng)審文化需要時(shí)間培養(yǎng)但一旦形成團(tuán)隊(duì)的代碼質(zhì)量和協(xié)作效率都會(huì)顯著提升。體會(huì)五評(píng)審數(shù)據(jù)要善用。評(píng)審數(shù)據(jù)可以用來(lái)發(fā)現(xiàn)流程問(wèn)題但不要用來(lái)考核個(gè)人。如果用評(píng)審數(shù)據(jù)來(lái)考核評(píng)審者評(píng)審者就會(huì)追求數(shù)量而忽視質(zhì)量甚至出現(xiàn)刷評(píng)審數(shù)量的情況。評(píng)審數(shù)據(jù)應(yīng)該用于流程優(yōu)化而不是個(gè)人績(jī)效評(píng)估。體會(huì)六評(píng)審工具要適配。沒(méi)有最好的評(píng)審工具只有最適合團(tuán)隊(duì)的評(píng)審工具。選擇評(píng)審工具時(shí)要考慮團(tuán)隊(duì)的技術(shù)棧、工作習(xí)慣、協(xié)作方式。不要盲目追求新工具也不要固守舊工具。工具是為人服務(wù)的不是人為工具服務(wù)。體會(huì)七評(píng)審能力要持續(xù)提升。評(píng)審能力不是一勞永逸的需要持續(xù)學(xué)習(xí)和練習(xí)。技術(shù)棧在變業(yè)務(wù)在變?cè)u(píng)審的標(biāo)準(zhǔn)和方法也要跟著變。保持學(xué)習(xí)的心態(tài)定期回顧自己的評(píng)審實(shí)踐不斷改進(jìn)評(píng)審方法。最后再分享一個(gè)小技巧如果你剛開始推行代碼評(píng)審不要一下子全面鋪開。先找一個(gè)愿意配合的小團(tuán)隊(duì)試點(diǎn)跑通流程后再逐步推廣。試點(diǎn)過(guò)程中收集反饋調(diào)整流程等流程成熟了再推廣到整個(gè)團(tuán)隊(duì)。這樣風(fēng)險(xiǎn)最小成功率最高。