1. 項(xiàng)目概述為什么我們需要開放的代碼審查先說結(jié)論open-code-review 不是什么高深莫測的框架它是一套把 code review 從走流程變成沉淀技術(shù)資產(chǎn)的工程實(shí)踐方案。我把它理解成三件事的組合一套開放的審查規(guī)則模板、一套能落地的工具鏈配置、一種讓團(tuán)隊(duì)愿意持續(xù)執(zhí)行的協(xié)作文化。三樣缺一不可——規(guī)則寫得再漂亮工具不配合成員不買賬最終還是會回到review 就是點(diǎn)個 approve的老路上。最早意識到這個問題是在一個十二人左右的后端團(tuán)隊(duì)。當(dāng)時我們每個 PR 都有至少兩個 reviewer看起來流程很完備但版本發(fā)出去之后 bug 率并沒有明顯下降。我抽了幾個典型事故反向追蹤發(fā)現(xiàn)這些 bug 所在代碼在 review 階段全都被看過而且都被Approved了。問題出在哪reviewer 根本沒看懂改動意圖或者說沒意識到自己應(yīng)該對什么負(fù)責(zé)。大家只是機(jī)械地打開 diff掃一眼有沒有明顯的語法錯誤、有沒有和現(xiàn)有風(fēng)格沖突就點(diǎn)了通過。這不是某個人的問題是整個團(tuán)隊(duì)的 review 價值觀出了問題。后來我們花了大概兩個迭代的周期把 code review 從審批動作改成了協(xié)作過程查閱了大量公開的最佳實(shí)踐資料也結(jié)合我們自己的業(yè)務(wù)特點(diǎn)逐步整理出了一套我們內(nèi)部稱為open-code-review的方案。這套方案最核心的變化是兩個第一把 review 的標(biāo)準(zhǔn)從代碼能不能跑提升到代碼該不該這么寫第二把 review 這個動作從 PR 提出后的階段前移到了開發(fā)過程中的每個關(guān)鍵決策點(diǎn)。為什么要強(qiáng)調(diào)開放因?yàn)橛行У?code review 本質(zhì)上是一種知識共享和風(fēng)險共擔(dān)機(jī)制如果審查過程封閉、標(biāo)準(zhǔn)藏在某幾個資深成員腦子里、結(jié)論靠拍腦袋那它就不可能穩(wěn)定地發(fā)揮作用。開放的審查標(biāo)準(zhǔn)、開放的流程模板、開放的自動檢查規(guī)則才能讓新成員快速進(jìn)入角色讓資深成員把精力放在真正需要人類判斷的地方。這套方案適合誰適合所有正在用 GitHub、GitLab 這類平臺做協(xié)作開發(fā)的團(tuán)隊(duì)尤其是那種幾十人規(guī)模、正在從能干活往干得穩(wěn)轉(zhuǎn)變的中小型團(tuán)隊(duì)。也適合那些一個人維護(hù)多個開源倉庫的獨(dú)立開發(fā)者——你同樣需要一套標(biāo)準(zhǔn)來控制外人提交進(jìn)來的代碼質(zhì)量。如果你剛帶團(tuán)隊(duì)可以從這套方案的流程部分直接抄如果你本身是團(tuán)隊(duì)成員想讓 review 不再流于形式這篇文章里的檢查清單和模板也能幫你在下一次 review 時立刻用上。2. 整體設(shè)計(jì)與核心思路從審批轉(zhuǎn)向協(xié)作2.1 傳統(tǒng) code review 為什么失靈在深入講 open-code-review 的設(shè)計(jì)之前先花點(diǎn)時間搞清楚一個根本問題為什么很多團(tuán)隊(duì)的 review 像走過場我觀察到的第一個原因是 review 的定位錯了。很多團(tuán)隊(duì)把 Code Review 當(dāng)成質(zhì)量門禁PR 不經(jīng)過 reviewer 的 approve 就不能合入這導(dǎo)致雙方的心態(tài)都扭曲了。提交方想的不是我需要你的意見而是我要說服你放行審查方想的也不是我?guī)湍惆言O(shè)計(jì)弄扎實(shí)而是我要找茬找不出茬來顯得我沒水平。這種對抗性關(guān)系下review 變成了辯論賽而不是設(shè)計(jì)討論會。第二個原因是審查的時間點(diǎn)太晚了。絕大多數(shù)團(tuán)隊(duì)是在代碼寫完之后才開始 review這時候大的設(shè)計(jì)問題已經(jīng)定型了。一個人悶頭寫了五天起了個不太合理的抽象層第五天晚上發(fā)了個八百行的 PRreviewer 就算看出來抽象層設(shè)計(jì)有問題面對已寫完的代碼心想的也是改起來成本太高算了算了最后只提點(diǎn)小意見放行。結(jié)果就是結(jié)構(gòu)性的缺陷永遠(yuǎn)帶著先發(fā)優(yōu)勢混進(jìn)主干。第三個原因是審查標(biāo)準(zhǔn)模糊。我問過我們團(tuán)隊(duì)的人你 review 的時候到底在看什么答案五花八門。有人看命名、有人看性能、有人只關(guān)心有沒有 TODO 沒刪干凈。不是他們不負(fù)責(zé)是沒有人告訴過他們什么樣的 code review 才算到位。在沒有統(tǒng)一標(biāo)準(zhǔn)的情況下review 質(zhì)量完全依賴個人經(jīng)驗(yàn)和直覺而個人經(jīng)驗(yàn)和直覺是最難復(fù)制、最不可靠的東西。2.2 開放式的三層審查模型所以 open-code-review 的設(shè)計(jì)基點(diǎn)是把 review 拆成三個層次每個層次有明確的目標(biāo)、時間點(diǎn)和參與人。第一層叫設(shè)計(jì)評審發(fā)生在寫代碼之前。哪怕只是變更一個內(nèi)部服務(wù)接口也應(yīng)該先說清楚這次的改動邊界。怎么實(shí)現(xiàn)不需要正式會議只需要在 PR 描述里寫一段設(shè)計(jì)背景 方案選擇 為什么這么選然后丟一兩句給相關(guān)同事看一眼。這個動作成本極低但能避免大量寫到一半發(fā)現(xiàn)方向錯了的情況。我們最開始做的時候也覺得麻煩后來慢慢養(yǎng)成了習(xí)慣形成了一種共識如果一段改動涉及跨服務(wù)調(diào)用或者數(shù)據(jù)模型變化必須先把方案說清楚再動手寫。第二層是差異審查就是大多數(shù)人理解的 code review發(fā)生在 PR 提出之后。這個層級的核心不是放大鏡逐行看而是帶著問題清單去看。問題清單不是我自己拍腦袋想的而是收集了團(tuán)隊(duì)里幾乎所有歷史事故和低質(zhì)量代碼的共性問題總結(jié)成了一份結(jié)構(gòu)化的 checklist后面我會有專門的章節(jié)講這份清單的細(xì)節(jié)。簡單說它覆蓋了正確性、可維護(hù)性、性能、安全、測試五個維度每個維度下有具體可回答的問題reviewer 只需要對照著過一遍。第三層是持續(xù)改進(jìn)發(fā)生在合入之后。每個迭代末我們會把這一期間通過 review 合入的代碼中后來出問題的部分拉出來復(fù)盤看是 review 過程中漏掉了還是當(dāng)時根本沒有相關(guān)標(biāo)準(zhǔn)。如果是后者就補(bǔ)充進(jìn)入清單讓下一輪 review 的標(biāo)準(zhǔn)更強(qiáng)。這聽起來很玄但我可以負(fù)責(zé)任地說這個循環(huán)跑三輪之后團(tuán)隊(duì)整體的代碼質(zhì)量就會有肉眼可見的提升。這個三層模型最大的好處是把 code review 從一個人人都能敷衍了事的質(zhì)量檢查動作變成了一套有節(jié)奏、有工具、有反饋的質(zhì)量協(xié)作流程。它不是某個人聰明而是系統(tǒng)性地讓每個參與者都更容易做對事。2.3 工具的定位人機(jī)分工的邊界工具在 open-code-review 里承擔(dān)的角色不是替代人的判斷而是把人從重復(fù)勞動里解放出來。我在設(shè)計(jì)工具鏈時有一個原則所有不需要人類判斷力就能發(fā)現(xiàn)的問題一律交給自動檢查所有需要設(shè)計(jì)權(quán)衡、業(yè)務(wù)上下文、長期演進(jìn)視角的問題才值得人類 review。這里有個很重要的邊界問題。比如代碼風(fēng)格這完全是機(jī)械判斷eslint、gofmt 這類工具看一眼就知道合不合規(guī)為什么要浪費(fèi) reviewer 的精力再比如 API 兼容性檢查、已知漏洞依賴掃描這明顯超出普通成員的知識范圍也應(yīng)該由機(jī)器人來做。真正需要人類 review 的是什么是這段改動的抽象是否合理、接口設(shè)計(jì)是否穩(wěn)健、異常處理是否考慮到了業(yè)務(wù)邊界、測試是否覆蓋了真正有風(fēng)險的路徑。這個邊界的劃分還直接影響一個數(shù)字一個 PR 平均需要多少分鐘的人工 review 時間。我們團(tuán)隊(duì)在沒有自動化工具時平均每個 PR 的 review 耗時大約是 28 分鐘其中大概有一半時間花在了風(fēng)格討論和明顯可以自動判斷的問題上。接入工具鏈之后每個 PR 的 review 時間降到了 15 分鐘左右而且剩余時間里討論的內(nèi)容質(zhì)量明顯更高了。2.4 為什么開放兩個字這么重要我反復(fù)強(qiáng)調(diào)開放不是概念包裝而是有實(shí)際原因的。把審查標(biāo)準(zhǔn)、清單、模板、工具配置全部放在團(tuán)隊(duì)的文檔庫里任何成員都能打開看都會知道我的代碼提交后會按照什么標(biāo)準(zhǔn)被評審這在心理層面就已經(jīng)改變了成員的編碼方式。我見過太多團(tuán)隊(duì)成員在提交代碼前根本不知道會被怎么評價于是提交的時候只憑自己的直覺猜測什么算好代碼結(jié)果 review 的時候被批得體無完膚時間長了要么擺爛要么逆反。開放還有一個更實(shí)際的價值降低新成員的上手成本。我們團(tuán)隊(duì)曾經(jīng)加入過一個剛從學(xué)校畢業(yè)的工程師第一個月寫的代碼平均每個 PR 打回三到四次不是因?yàn)樗讲疃且驗(yàn)闆]有人告訴過她什么算過得了 review 的代碼。后來我們把 checklist 直接發(fā)給她讓她在提交之前自己先過一遍打回率馬上從四次降到了不足一次。這不是什么玄學(xué)純粹是標(biāo)準(zhǔn)透明了人的行為就會自動往標(biāo)準(zhǔn)上靠。所以open-code-review 里的open指的既不是某個開源軟件的名字也不是說所有倉庫都要公開而是說審查的規(guī)則、流程、標(biāo)準(zhǔn)、工具對每個參與者透明可見。你可以把這個理解為團(tuán)隊(duì)里的每一次 code review都是在按照一份所有人都看得見的公開契約進(jìn)行。3. 核心細(xì)節(jié)與實(shí)操要點(diǎn)一份能直接用的 Review 清單3.1 五個審查維度的設(shè)計(jì)邏輯接下來是整篇博客里最值得抄作業(yè)的部分一份我在實(shí)際團(tuán)隊(duì)里打磨過的 code review 檢查清單。它分成五個維度每個維度下有一組可以直接回答是/否的問題。正確性維度上的核心是狀態(tài)變更的完整性。讀了代碼之后我會問自己幾個問題這個改動改變了哪些狀態(tài)所有狀態(tài)都有對應(yīng)的更新路徑嗎有沒有可能走到中間狀態(tài)舉個典型例子更新用戶密碼的功能只改了數(shù)據(jù)庫字段卻沒有清理緩存里的舊密碼這就是典型的狀態(tài)更新遺漏。這類 bug 靠編譯器發(fā)現(xiàn)不了靠測試可能也發(fā)現(xiàn)不了如果測試直接查庫而不是走緩存只能靠 review 時對狀態(tài)流轉(zhuǎn)的推演?？删S護(hù)性關(guān)注的不是今天能不能用而是三個月后別人能不能改。我會看新增的抽象是讓代碼更簡單了還是引入了一層不必要的間接改動是遵循了文件里已有的模式還是為了滿足某個個性化偏好另起爐灶方法長度和職責(zé)劃分合理嗎命名是否名副其實(shí)還是起了個managerutil這種含混的名字強(qiáng)行糊弄過去性能審查不是讓你去摳每個循環(huán)的微優(yōu)化而是關(guān)注有沒有明顯的數(shù)量級問題。比如這段邏輯有沒有把原本 O(n) 的操作寫成 O(n2)有沒有在循環(huán)里發(fā) SQL 查詢有沒有對熱點(diǎn)路徑增加無謂的開銷如果改動涉及接口響應(yīng)體是不是比原來大了很多這些才是 review 階段值得關(guān)注的問題至于臨時變量的分配方式、字符串拼接的細(xì)節(jié)交給 profiler 去管。安全審查要看的不是滲透測試那種攻防對抗而是常見的低級漏洞模式用戶輸入有沒有被校驗(yàn)就拼進(jìn) SQL 或 HTML權(quán)限檢查是放在了前端還是后端敏感信息有沒有被打進(jìn)日志有沒有新增的外部依賴存在已知漏洞這些問題的答案在很大程度上決定了代碼合入后會不會變成事故的導(dǎo)火索。測試維度的核心是風(fēng)險覆蓋和有效性的平衡。有沒有為核心邏輯補(bǔ)充單測新增的測試是在驗(yàn)證真實(shí)行為還是在為了覆蓋率數(shù)字而寫斷言失敗路徑有沒有被測試到異常分支是否被覆蓋我要重點(diǎn)說明的是我見過太多團(tuán)隊(duì)測試覆蓋率 80% 以上、能跑的業(yè)務(wù)測試占比卻很低的情況。寫測試的時候如果用make sure it works的心態(tài)出來的測試就是典型的無效資產(chǎn)。3.2 關(guān)于 PR 規(guī)模的量化經(jīng)驗(yàn)還有一個經(jīng)常被忽視、但實(shí)際影響體驗(yàn)和質(zhì)量的參數(shù)PR 的大小。我個人的經(jīng)驗(yàn)供參考一次性合入的 PR去掉鎖文件、生成文件之后代碼變更應(yīng)該控制在 200 到 400 行之間寧可拆分成多個小 PR也別壓成一個巨型 PR。這個觀察有研究數(shù)據(jù)佐證——有研究者分析過大量 pull request 數(shù)據(jù)后發(fā)現(xiàn)超過 400 行的 PRreview 效果會明顯下降而 200 行左右的 PR 最容易獲得高質(zhì)量反饋。如果你做了一個超過 800 行的改動最需要做的不是硬著頭皮發(fā) PR而是先自己問一句這個改動真的只能一次做完嗎90% 的情況下答案是可以拆的?？梢园凑者壿嫴襟E拆成先引入抽象接口再遷移舊調(diào)用方最后刪除舊實(shí)現(xiàn)三個順序 PR每個 PR 單獨(dú)可合入、可回滾review 起來也更輕松。我還在團(tuán)隊(duì)里定了兩個死規(guī)矩一個是鎖文件或構(gòu)建生成物單獨(dú)提交不混進(jìn)功能主改動里另一個是格式化、重命名這類純重構(gòu)操作要么單獨(dú)一個 PR要么在描述里顯著標(biāo)注本 PR 不含邏輯變更否則 reviewer 會花好幾輪去辨別哪些是真正有業(yè)務(wù)影響的改動。3.3 好 PR 描述長什么樣PR 描述是整個 review 環(huán)節(jié)里被低估得最厲害的部分。一個好的 PR 描述相當(dāng)于把上下文直接塞進(jìn) reviewer 腦子里讓 ta 不用從零開始猜你為什么要這么改。我習(xí)慣的模板是固定的背景業(yè)務(wù)上為什么要做這個改動有沒有對應(yīng)的 issue 或需求單方案技術(shù)上的實(shí)現(xiàn)思路是什么為什么選這個方案不選另一個影響面改了哪些模塊有沒有可能影響其他功能測試計(jì)劃自己測過什么測試覆蓋率有沒有變化驗(yàn)證截圖或日志如果涉及 UI 或接口行為提供退出證據(jù)。這個模板不是我從網(wǎng)上抄的而是我們從幾個月的實(shí)踐里總結(jié)出來的。填過幾次之后你就會發(fā)現(xiàn)寫清楚這五部分的 PRreviewer 的回復(fù)質(zhì)量和速度都會上一個臺階。因?yàn)?ta 能快速聚焦到你的方案對不對而不是花時間理解你要解決什么問題。下面是一個簡化的、可直接復(fù)制使用的 PR 描述模板## 背景 這里寫業(yè)務(wù)需求和背景附上相關(guān) issue 鏈接 ## 方案 這里寫技術(shù)實(shí)現(xiàn)思路如果有多方案對比也寫出來 ## 影響面 - 影響的服務(wù)/模塊 - 依賴是否存在破壞性變更 - 需要重點(diǎn)回歸的功能 ## 測試 - 單元測試覆蓋了 XX 場景覆蓋率從 XX% 變?yōu)?XX% - 手工測試在本地/測試環(huán)境驗(yàn)證了 XX 流程 - 風(fēng)險點(diǎn)XX 場景暫時沒有覆蓋原因 XX ## 驗(yàn)證證據(jù) 截圖或日志粘貼區(qū)3.4 開源協(xié)議與合規(guī)檢查當(dāng)你的團(tuán)隊(duì)在代碼庫里使用了第三方開源組件code review 清單里還應(yīng)該增加一個容易被忽略的維度開源協(xié)議合規(guī)。我們團(tuán)隊(duì)曾經(jīng)在一個 SDK 的依賴樹里發(fā)現(xiàn)了一個 MPL-2.0 協(xié)議的庫而我們當(dāng)時的產(chǎn)品閉源交付如果不做規(guī)避處理會帶來不必要的協(xié)議風(fēng)險。后來我們就把新增第三方依賴時必須檢查其開源協(xié)議寫進(jìn)了 review 清單并且在 CI 里加入了一個基礎(chǔ)的 license-check 步驟凡是新增依賴但協(xié)議不明或與公司分發(fā)方式?jīng)_突的直接通報提醒。這個細(xì)節(jié)看起來跟日常業(yè)務(wù)功能開發(fā)無關(guān)但它真實(shí)存在于所有工程師的協(xié)作現(xiàn)場而且是不開放就給大爺們埋雷的典型例子——如果審查標(biāo)準(zhǔn)不透明new grad 根本不會知道自己在不知情的情況下引入了一個協(xié)議風(fēng)險。4. 實(shí)操過程工具鏈配置與自動化落地4.1 檢查工具的最小可用組合如果說清單是 open-code-review 的軟件那一組趁手工具就是它的硬件。我強(qiáng)烈建議團(tuán)隊(duì)至少配置三類工具代碼風(fēng)格檢查工具、靜態(tài)分析工具和測試覆蓋報告工具。代碼風(fēng)格檢查工具的選擇取決于技術(shù)棧前端用 eslint prettierPython 用 ruffGo 用 gofmt golangci-lintJava 用 Checkstyle 加 SpotBugs。這類工具不需要人工判斷就應(yīng)該作為 CI 的第一道門卡住。我在團(tuán)隊(duì)里的做法是把 eslint 和 prettier 的檢查直接掛到 pre-commit hook 上問題在本地就能改掉不用等 CI 跑掛了再回來看一眼 diff。靜態(tài)分析工具的選擇就要稍微講究一些因?yàn)樗恼`報率比風(fēng)格工具要高。我傾向于先開一個保守的規(guī)則集跑一兩個迭代之后根據(jù)誤報情況逐步放寬或收緊。不要第一天就開到最嚴(yán)格模式不然團(tuán)隊(duì)成員一天到晚都在應(yīng)付誤報對工具本身的信任感會下降。測試覆蓋報告工具的核心不是覆蓋率數(shù)字本身而是新增代碼覆蓋率這個指標(biāo)。GitHub 有一款 free 的 coverage report 插件可以在 PR 上自動評論新增代碼的覆蓋率變化。我使用它的經(jīng)驗(yàn)是覆蓋率的硬性閾值設(shè)為 80% 比較合理但真正要緊的不是全局覆蓋率而是新代碼的覆蓋不能比原有代碼低太多。4.2 在 GitHub Actions 里搭一個自動化評審工作流工具鏈的落地最直觀的方式是在 GitHub Actions 里編排。我分享一個我實(shí)際用過的、可復(fù)用的 workflow 片段邏輯是提交 PR 后至少跑四道自動檢查——語法、lint、測試、構(gòu)建。如果基礎(chǔ)檢查全過了再跑靜態(tài)分析和服務(wù)級別的冒煙測試。這個 workflow 不是讓機(jī)器人真的代替人做 review而是把重復(fù)勞動前置讓人把時間花在更重要的事上。name: ci on: pull_request: types: [opened, synchronize, reopened] jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Setup Node uses: actions/setup-nodev4 with: node-version: 20 - name: Install dependencies run: npm ci - name: Run lint run: npm run lint test: runs-on: ubuntu-latest needs: lint steps: - uses: actions/checkoutv4 - name: Setup Node uses: actions/setup-nodev4 with: node-version: 20 - name: Install dependencies run: npm ci - name: Run unit tests run: npm run test:coverage build: runs-on: ubuntu-latest needs: test steps: - uses: actions/checkoutv4 - name: Setup Node uses: actions/setup-nodev4 with: node-version: 20 - name: Install dependencies run: npm ci - name: Build run: npm run build這套流程的價值在于任何一個 PR 在進(jìn)入人工 review 之前先經(jīng)過一個完全確定性的自動檢查階段。這臺機(jī)器上能過這種扯皮問題在 CI 檢查面前徹底消失reviewer 拿到手的就是一個已經(jīng)能用、只是還沒討論設(shè)計(jì)好壞的 PR。實(shí)測下來這套流程把無效討論時間壓縮了至少三分之一剩下的都是真正需要人類見解的決策。如果你是 GitLab 用戶原理一樣只是在.gitlab-ci.yml里寫成 stages 結(jié)構(gòu)。工具不同但設(shè)計(jì)思想完全是一套。4.3 用機(jī)器人處理人類不該看的噪音除了基礎(chǔ) CI我還引入了另一類工具review 機(jī)器人。這類工具的核心作用是把大量重復(fù)性、機(jī)械性的審查結(jié)論自動貼在 PR 評論里節(jié)省人類的注意力。我當(dāng)時選了 danger.js 這類方案它的好處是用 JavaScript 就可以寫檢查規(guī)則團(tuán)隊(duì)成員學(xué)習(xí)成本極低。我們給它布了幾條規(guī)則PR 描述缺失時自動提醒提交者補(bǔ)充鎖文件和依賴文件有變更時注明需要人工復(fù)核超過 400 行的 PR自動打上建議拆分為更小 PR的提示。這些規(guī)則都極其簡單但很實(shí)際因?yàn)樗鼈兇_保的人類的注意力不會被瑣碎檢查消耗掉。下面是 danger.js 的一個示例配置片段// dangerfile.js import { danger, fail, markdown, warn } from danger; import { readFileSync } from fs; const pr danger.github.pr; const additions pr.additions; const changes pr.changed_files; // 1. 描述是否為空白或過于簡短 if (!pr.body || pr.body.length 30) { fail(請補(bǔ)充 PR 描述至少說明背景和測試計(jì)劃); } // 2. 大 PR 預(yù)警 if (additions 400) { warn(這個 PR 新增了 ${additions} 行代碼超過 400 行建議拆分成更小的子 PR。); } else if (additions 800) { fail(新增代碼超過 800 行請拆分后再提交。); } // 3. 鎖文件變更和依賴變化提醒 const packageFiles new Set([ package-lock.json, yarn.lock, pnpm-lock.yaml, requirements.txt, go.mod, go.sum ]); const changedPackageFiles danger.git.modified_files.filter((f) packageFiles.has(f) ); if (changedPackageFiles.length 0) { markdown(檢測到依賴文件變更請人工確認(rèn)沒有引入新的安全風(fēng)險。); } // 4. 檢查新增代碼是否附帶測試文件 const addedCodeFiles danger.git.created_files.filter((f) /\.(ts|js|go|py)$/.test(f) !/\.test\.|\.spec\./.test(f) ); const addedTestFiles danger.git.created_files.filter((f) /\.test\.|\.spec\./.test(f) ); if (addedCodeFiles.length 0 addedTestFiles.length 0) { warn(新增代碼文件沒有配套的新增測試文件。); }這套機(jī)器人規(guī)則我們跑了半年最大的收益不是省下了多少時間而是讓提交一個體面的 PR變成了一個自動被檢查的顯式要求而不是靠某個人反復(fù)在群里苦口婆心地提醒。4.4 人機(jī)分工的邊界怎么定才算合理工具鏈配好了還有一個新問題自動檢查和人肉 review 之間邊界到底劃在哪里我的經(jīng)驗(yàn)是把握一個原則低風(fēng)險、高確定性的檢查交給機(jī)器高風(fēng)險、需要上下文理解的判斷留給人。比如某個函數(shù)是否多了不必要的抽象機(jī)器很難判斷因?yàn)樗枰肋@個模塊未來的演進(jìn)方向但某個錯誤信息是不是包含敏感信息、某個循環(huán)里是不是查了 N 次數(shù)據(jù)庫機(jī)器可以檢查出模式也可以把人引到正確的位置上。我們在這個原則下調(diào)整過好多次機(jī)器人規(guī)則最終穩(wěn)定下來的一套規(guī)則就只做提醒不做攔截因?yàn)樾问竭^強(qiáng)的攔截會破壞團(tuán)隊(duì)對工具的信任。另外自動化檢查在一個 PR 的人工 review結(jié)束后可以再跑一輪差分檢查比如確認(rèn)上一輪 reviewer 提的必須改的注釋是否真的對應(yīng)修改了——但我們沒有做那么強(qiáng)的自動化因?yàn)楝F(xiàn)在的工具要做到這點(diǎn)還比較笨重我們的做法是依賴 reviewer 自己 revisit 一遍。4.5 把 checklist 做成自動化的記憶前面提到的人工 checklist其實(shí)也可以沉淀到工具鏈里。GitHub 的 PR 模板天然支持 checkbox 列表你可以把 checklist 放在 PR 描述模板里讓每個提交者先勾選自檢再請求 review。這一步成本極低但效果極好。我們的做法是把 checklist 做成 PR 模板的一部分而且嚴(yán)格控制問題的數(shù)量——不要超過 10 個核心問題否則提交者會機(jī)械性全勾上反而失去自檢的意義。我把我們團(tuán)隊(duì)現(xiàn)用的 PR 模板中最重要的列表寫出來供參考我是否在本地跑通了所有相關(guān)測試我是否檢查過新增代碼可能引入的狀態(tài)不一致我是否確認(rèn)新增依賴的開源協(xié)議與當(dāng)前分發(fā)方式兼容我是否更新了相關(guān)文檔或注釋我是否在測試計(jì)劃里覆蓋了失敗路徑我是否檢查過日志里不會出現(xiàn)敏感信息5. 常見問題與排查技巧實(shí)錄5.1 PR 太久沒人 review怎么辦幾乎每個團(tuán)隊(duì)都會遇到?jīng)]人在 PR 上及時反饋的問題。這不一定是誰不負(fù)責(zé)而是 review 作為異步協(xié)作任務(wù)天然排在各自的開發(fā)任務(wù)后面。但也正是因?yàn)樘烊慌旁诤竺嫠驼娴呐诺较轮苋チ恕Ｎ业奶幚斫?jīng)驗(yàn)是兩條腿走路。第一條是讓沒人 review這件事變得讓所有人可見。我們設(shè)了一個自動化規(guī)則PR 發(fā)出 4 小時后仍沒有 review 時機(jī)器人會把 PR 鏈接轉(zhuǎn)發(fā)到對應(yīng)的 channel12 小時后仍沒有任何 review 動態(tài)它會自動提到倉庫的 maintainer。不要小看這個簡單的機(jī)制——公開可見本身就能帶來很大的行動壓力。第二條是給 review 設(shè)定明確的 SLA 承諾。比如我們約定工作時間內(nèi) 4 小時內(nèi)給出首個 response24 小時內(nèi)完成 review。這里的 response 不一定是完整的 approve也可以是一句我今晚沒空看明天早上給你看或者我已開始看預(yù)計(jì)下午給完整意見。先動起來遠(yuǎn)比徹底看完重要。5.2 reviewer 意見和提交者想法不一致怎么辦review 過程中最消耗情緒的就是設(shè)計(jì)路線之爭。我見過一個典型的 case一個資深的 reviewer 認(rèn)為某段邏輯應(yīng)該抽成一個 service而提交者認(rèn)為直接寫在調(diào)用方更直觀簡單。兩個人在 PR 下面來回刷了十幾條評論誰也沒說服誰最后首席工程師介入才平息。我的經(jīng)驗(yàn)是review 意見里涉及風(fēng)格和偏好層面的內(nèi)容應(yīng)該明確標(biāo)注為個人傾向而不是必須修改。這也意味著在團(tuán)隊(duì)層面要有爭議升級的機(jī)制——比如當(dāng)某一類的意見反復(fù)出現(xiàn)、且雙方無法達(dá)成一致時需要盡快讓更多有相關(guān)經(jīng)驗(yàn)的人參與進(jìn)來做集體決策。同時在 review 意見的表述上我要求團(tuán)隊(duì)成員用提議而不是命令式句式例如把這里改成只讀會不會更安全而不是你這里必須用 final。同樣是表達(dá)意見前者更容易被當(dāng)作建議理解后者容易產(chǎn)生壓力特別是兩個字容易在表格和 diff 的上下文里顯得異常刺耳。5.3 新人每次 PR 都被打回很多次感覺挫敗怎么辦這是個很真實(shí)的管理挑戰(zhàn)。新人提交代碼被打回太多次會越來越不自信甚至開始過度依賴 reviewer 的口頭指導(dǎo)來寫代碼。我們的解法就是把標(biāo)準(zhǔn)完全拆開了給 ta。第一步是給新人解釋清楚整個 review 的評判標(biāo)準(zhǔn)把我們那份 checklist 發(fā)過去讓 ta 在每次提交前先自評一遍。第二步是為新成員安排一個固定的review 伙伴而不是讓 ta 每次面對不同的 reviewer。這個伙伴的重要性在于幾次 review 之后 ta 能夠了解這位新人的常見錯誤模式給出的反饋會更有針對性新人也不會每次都是從頭面對一個陌生人的緊張感。第三步是明確告訴新人review 意見里標(biāo)注了 nitnitpick 瑣碎小建議的內(nèi)容只是錦上添花可以不改不是必須服從。這套組合拳打下來團(tuán)隊(duì)里新人在第二個月的 PR 打回率就明顯下降三個月后基本和資深成員持平。5.4 自動化檢查總在報毫無意義的誤報吵得人煩誤報是引入自動化工具之后幾乎必然會碰上的問題處理不好會讓團(tuán)隊(duì)對工具失去信任。我的建議非常務(wù)實(shí)寧可少報不要亂報。一個 lint 規(guī)則如果誤報率超過 20%那就該考慮關(guān)掉或者改成 warn 級別而不是讓每個開發(fā)都學(xué)會如何繞過這條規(guī)則。具體到配置層面靜態(tài)分析工具的規(guī)則集采用漸進(jìn)式開規(guī)則的策略。上線一個新規(guī)則前先在倉庫里跑一遍看歷史代碼會被報出多少條。如果歷史積壓問題超過兩位數(shù)這條規(guī)則要么先不開要么開了也僅提示不攔截等團(tuán)隊(duì)消化完存量再嚴(yán)格化。我在這上面踩過幾次坑之后發(fā)現(xiàn)的規(guī)律是——工具信任一旦崩塌再想讓團(tuán)隊(duì)好好看自動檢查結(jié)果要花數(shù)倍的時間去重建。5.5 代碼合入后才發(fā)現(xiàn) review 漏掉了關(guān)鍵 bug該問責(zé)嗎這條我特別想聊因?yàn)楹芏鄨F(tuán)隊(duì)在這個問題上的處理爛透了。一旦出線上故障第一反應(yīng)就是查 blame、查是誰第一時間放行。但高效能的團(tuán)隊(duì)不會把 review 失誤當(dāng)個人錯誤來追責(zé)而是當(dāng)系統(tǒng)設(shè)計(jì)缺陷來分析。我們要問的不是這個 reviewer 為什么沒看出來而是為什么我們的 check 機(jī)制允許這類 bug 未被攔截然后改進(jìn)系統(tǒng)讓下一次同樣的錯誤變得更難發(fā)生。我們團(tuán)隊(duì)在復(fù)盤會上有個不成文的規(guī)矩不點(diǎn)名只說機(jī)制。每次復(fù)盤某個 review 漏掉的高風(fēng)險缺陷我們都會問兩個問題當(dāng)時那類風(fēng)險是不是在 checklist 覆蓋范圍內(nèi)如果不在這次的事故正好證明需要補(bǔ)上它如果在那說明是執(zhí)行問題就要去看是不是流程壓力過大、是不是 PR 太大、是不是 reviewer 同時要看的 PR 太多——這些問題仍然指向系統(tǒng)改進(jìn)而不是個人懲罰。6. 如何從零開始在你的團(tuán)隊(duì)落地 open-code-review6.1 第一步先定極小規(guī)則集別貪多求全我知道很多團(tuán)隊(duì)的負(fù)責(zé)人看完這類文章之后第一反應(yīng)是想把所有建議一次性落地。但我必須潑一盆冷水一次引入太多規(guī)則團(tuán)隊(duì)會像應(yīng)對一個食之無味棄之可惜的新系統(tǒng)一樣迅速把它變成又一個效率負(fù)擔(dān)。最穩(wěn)妥的做法是選擇一個正在活躍迭代的倉庫先只引入三個東西PR 模板、一個基礎(chǔ) lint 配置和一條 CI 檢查。等這兩三樣跑順了再逐步加入 review 機(jī)器人、覆蓋率檢查、協(xié)議檢查等。第一批規(guī)則數(shù)量控制在 5 到 10 條之內(nèi)。比如定義 PR 描述必須包含哪些字段、PR 超過多少行需要拆、哪些枚舉必須用共享常量而不是硬編碼。這些規(guī)則要符合該倉庫的實(shí)際技術(shù)棧和團(tuán)隊(duì)當(dāng)下的痛點(diǎn)。我的經(jīng)驗(yàn)是第一批規(guī)則最好只解決你們最近三個月內(nèi)實(shí)際踩過的坑而不是去預(yù)防那些也許永遠(yuǎn)不發(fā)生的風(fēng)險——預(yù)防永遠(yuǎn)是第二順位的事。6.2 第二步讓 review 的正確姿勢變成公共知識規(guī)則定好之后還需要讓團(tuán)隊(duì)的每個成員都明確知道我應(yīng)該怎樣做一次 review。我會組織一場一小時的分享會但講的不是 PPT 里的抽象理論而是拿一個真實(shí)的歷史 PR 當(dāng)案例演示一個合格的 reviewer 會怎么讀一個 diff。我第一次做這個演示時現(xiàn)場拆了一個三百行的 PR按我們清單的五個維度逐條說明哪些地方會觸發(fā)我的疑問哪些地方值得深入看哪些地方可以直接跳過。分享結(jié)束后有同事跑來跟我說原來 review 不是從頭到尾讀一遍而是帶著一堆問題去代碼里找答案。這個細(xì)節(jié)我特別想強(qiáng)調(diào)——code review 的正確姿勢不是從第一個 diff 看到最后一個 diff而是先讀 PR 描述搞清楚這次改動的意圖和范圍再帶著問題跳讀關(guān)鍵的改動點(diǎn)。這樣既快又能抓住重點(diǎn)。很多低質(zhì)量的 review 是因?yàn)?reviewer 從頭到尾機(jī)械地讀反而漏掉了真正要關(guān)注的核心。6.3 第三步按迭代復(fù)盤持續(xù)校準(zhǔn)規(guī)則規(guī)則和工具落地后最關(guān)鍵的就是按迭代做復(fù)盤。這個復(fù)盤不需要多頻繁一次迭代結(jié)束的最后一天拿出來 30 分鐘就夠了。打開這段時間合入的 PR挑出質(zhì)量最高的一個和質(zhì)量最低的一個分別討論一下高質(zhì)量 PR 為什么好是描述寫得好還是拆得好還是測試補(bǔ)充得扎實(shí)低質(zhì)量 PR 暴露了哪條規(guī)則沒有起到作用我們團(tuán)隊(duì)就是通過這個方式持續(xù)調(diào)整規(guī)則的。曾經(jīng)有一條PR 內(nèi)不要出現(xiàn)不必要的注釋掉的代碼規(guī)則執(zhí)行了幾輪后我們發(fā)現(xiàn)這條規(guī)則過于瑣碎而且容易誤判就把它收回了。又比如新增了改動涉及配置時必須在 PR 描述中注明目標(biāo)環(huán)境這條規(guī)則是因?yàn)橛幸淮闻渲米兏堑搅松壛鞒滩疟┞冻鰜韱栴}。這種持續(xù)校準(zhǔn)的過程正是 open-code-review 的核心精神——規(guī)則不是鐵板一塊地壓下來的而是在團(tuán)隊(duì)協(xié)作中被持續(xù)打磨和完善。6.4 第四步為愿意把 review 做好的成員留出空間最后聊一個可能跟前三步都不太一樣但我認(rèn)為同樣重要的點(diǎn)。很多團(tuán)隊(duì)的激勵體系里code review 是不被看見的幕后工作成員主動好好 review 了沒有直接的回報和反饋。這導(dǎo)致認(rèn)真做 review 的人逐漸被搭便車心態(tài)消耗掉。我的經(jīng)驗(yàn)是一方面要在團(tuán)隊(duì)里公開肯定 review 做得好的成員——不只是夸 ta 發(fā)現(xiàn)了 bug更要點(diǎn)名謝謝 ta 提出的建設(shè)性建議讓設(shè)計(jì)更簡潔。另一方面在評估績效和成長時要把 review 質(zhì)量納入考量的范疇。如果一個成員這半年做了大量高價值的 review 反饋那這一點(diǎn)應(yīng)該被記錄和認(rèn)可即便 ta 自己交付的代碼量不算最大。不然的話open-code-review 再怎么強(qiáng)調(diào)參與感最終也會輸給真實(shí)的激勵機(jī)制。激勵機(jī)制不跟上任何協(xié)作流程都走不遠(yuǎn)。寫在后面我在實(shí)際推動這套方案之前也懷疑過是不是把簡單的事情搞復(fù)雜了。但跑了幾個迭代之后我最大的感受是好的 code review 不是靠幾個認(rèn)真的人撐起來的而是靠一套清晰、開放、可迭代的規(guī)則讓所有人都能在同一個水位線上參與。這個水位線才是團(tuán)隊(duì)整體代碼質(zhì)量真正的下限。把下限抬起來比期待每個人都成為頂尖寫手要現(xiàn)實(shí)得多也穩(wěn)定得多。