1. 代碼評(píng)審工具鏈的現(xiàn)狀與 open-code-review 的切入點(diǎn)1.1 為什么我又造了一個(gè)代碼評(píng)審工具先說(shuō)結(jié)論open-code-review是一個(gè)開(kāi)源的、可本地部署的代碼評(píng)審輔助工具核心目標(biāo)是把「人工逐行看 diff」這件事里最枯燥、最重復(fù)、最容易漏掉的部分自動(dòng)化掉。它不是一個(gè) CI/CD 平臺(tái)也不是一個(gè)靜態(tài)代碼分析器的替代品而是一個(gè)夾在「提交代碼」和「人工評(píng)審」之間的中間層。我做過(guò)幾年團(tuán)隊(duì)里的代碼評(píng)審把關(guān)人最深的體會(huì)是評(píng)審質(zhì)量極度依賴評(píng)審人當(dāng)天的狀態(tài)。狀態(tài)好的時(shí)候能發(fā)現(xiàn)空指針、邊界條件、并發(fā)競(jìng)爭(zhēng)狀態(tài)差的時(shí)候一個(gè)幾百行的 diff 掃兩眼就點(diǎn)了 Approve。更麻煩的是團(tuán)隊(duì)里每個(gè)人的關(guān)注點(diǎn)不一樣——有人只看邏輯有人只看命名有人只看有沒(méi)有寫測(cè)試。結(jié)果就是同一個(gè) MRMerge Request被不同的人反復(fù)問(wèn)同樣的問(wèn)題溝通成本極高。open-code-review想解決的就是這個(gè)把「機(jī)械性檢查」和「需要人類判斷的部分」拆開(kāi)。機(jī)械性的東西——比如代碼風(fēng)格、明顯的壞味道、缺失的測(cè)試覆蓋、潛在的空指針風(fēng)險(xiǎn)——交給工具先跑一遍輸出一份結(jié)構(gòu)化的評(píng)審報(bào)告人類評(píng)審員拿到這份報(bào)告后只需要聚焦在架構(gòu)合理性、業(yè)務(wù)邏輯正確性這些真正需要經(jīng)驗(yàn)判斷的地方。這個(gè)工具適合誰(shuí)用三類人一是中小團(tuán)隊(duì)的技術(shù)負(fù)責(zé)人沒(méi)有資源搭建復(fù)雜的代碼質(zhì)量平臺(tái)但又想有個(gè)統(tǒng)一的評(píng)審基線二是開(kāi)源項(xiàng)目的維護(hù)者面對(duì)大量外部貢獻(xiàn)者的 PR需要快速篩選出哪些值得細(xì)看三是個(gè)人開(kāi)發(fā)者想在提交代碼前自己先過(guò)一遍減少被 reviewer 打回的次數(shù)。1.2 它和現(xiàn)有工具的區(qū)別在哪市面上代碼質(zhì)量工具不少靜態(tài)分析有 SonarQube、ESLint、Pylint 這類CI 平臺(tái)有 Jenkins、GitLab CI、GitHub Actions。open-code-review的定位不是取代它們而是補(bǔ)上它們沒(méi)覆蓋的那一段。靜態(tài)分析工具擅長(zhǎng)的是「規(guī)則匹配」——你定義一條規(guī)則它掃描全量代碼找違規(guī)。但代碼評(píng)審場(chǎng)景下我們關(guān)心的往往不是「全量代碼里有沒(méi)有問(wèn)題」而是「這次改動(dòng)引入了什么問(wèn)題」。這兩者的差別很大。舉個(gè)例子一個(gè)文件里有 50 個(gè)函數(shù)其中 49 個(gè)是歷史遺留的爛代碼你這次只改了第 50 個(gè)。靜態(tài)分析工具會(huì)報(bào) 49 個(gè)問(wèn)題噪音極大而open-code-review只關(guān)注你這次 diff 涉及的那幾行輸出的是「你這次改動(dòng)可能帶來(lái)的風(fēng)險(xiǎn)」。另一個(gè)區(qū)別是輸出形式。靜態(tài)分析工具輸出的是問(wèn)題列表按嚴(yán)重程度排序open-code-review輸出的是評(píng)審建議按「需要人工確認(rèn)的程度」排序。前者是「這里有問(wèn)題」后者是「這里建議你看一眼因?yàn)椤?。這個(gè)「因?yàn)椤购苤匾雅袛嘁罁?jù)也一并給出了評(píng)審員不需要再去翻文檔查規(guī)則。我實(shí)測(cè)下來(lái)的感受是把open-code-review掛在 CI 流程里作為一個(gè)「預(yù)評(píng)審」步驟能把人工評(píng)審的時(shí)間壓縮 40% 左右。當(dāng)然這個(gè)數(shù)字因團(tuán)隊(duì)而異但方向是明確的——機(jī)械性工作前置人類專注判斷。1.3 核心設(shè)計(jì)思路分層評(píng)審open-code-review的架構(gòu)設(shè)計(jì)遵循一個(gè)原則分層評(píng)審逐級(jí)收斂。整個(gè)流程分三層第一層是語(yǔ)法與格式層這一層完全自動(dòng)化不需要人類介入。檢查內(nèi)容包括縮進(jìn)是否一致、行尾空格、文件末尾換行、導(dǎo)入順序、命名規(guī)范駝峰/下劃線。這一層的輸出是「通過(guò)/不通過(guò)」不通過(guò)就直接打回不進(jìn)入下一層。第二層是語(yǔ)義與風(fēng)險(xiǎn)層這一層半自動(dòng)化工具給出風(fēng)險(xiǎn)提示人類決定是否采納。檢查內(nèi)容包括空指針風(fēng)險(xiǎn)、資源未釋放、異常吞沒(méi)、并發(fā)訪問(wèn)共享狀態(tài)、SQL 拼接、硬編碼密鑰。這一層的輸出是「風(fēng)險(xiǎn)點(diǎn)列表 建議」評(píng)審員逐條確認(rèn)。第三層是架構(gòu)與業(yè)務(wù)層這一層完全由人類負(fù)責(zé)工具不介入。內(nèi)容包括模塊劃分是否合理、接口設(shè)計(jì)是否可擴(kuò)展、業(yè)務(wù)邏輯是否符合需求、是否有更好的實(shí)現(xiàn)方案。這一層是評(píng)審的核心價(jià)值所在也是工具永遠(yuǎn)無(wú)法替代的部分。這個(gè)分層的好處是每一層的評(píng)審標(biāo)準(zhǔn)是明確的不會(huì)出現(xiàn)「這個(gè)到底算不算問(wèn)題」的扯皮。第一層不過(guò)直接打回沒(méi)有討論空間第二層有爭(zhēng)議評(píng)審員可以標(biāo)記「已知悉接受風(fēng)險(xiǎn)」第三層才是真正需要坐下來(lái)討論的。2. 核心功能模塊拆解與實(shí)現(xiàn)要點(diǎn)2.1 diff 解析引擎怎么準(zhǔn)確拿到「這次改了什么」整個(gè)工具的地基是 diff 解析。如果 diff 解析不準(zhǔn)后面所有分析都是空中樓閣。open-code-review的 diff 解析引擎需要處理幾種輸入格式Git 原生的 unified diff、GitHub/GitLab API 返回的 patch 字段、以及本地文件對(duì)比生成的 diff。這里有個(gè)坑我踩過(guò)不同平臺(tái)返回的 diff 格式有細(xì)微差別。比如 GitLab 的 API 在某些情況下會(huì)把\ No newline at end of file這個(gè)標(biāo)記放在錯(cuò)誤的位置導(dǎo)致解析出來(lái)的行號(hào)偏移。解決辦法是在解析時(shí)做一次「行號(hào)校驗(yàn)」——用 diff 里的 hunk header -a,b c,d 去反推每一行的原始行號(hào)和新行號(hào)如果發(fā)現(xiàn)不一致就以 hunk header 為準(zhǔn)修正。解析后的數(shù)據(jù)結(jié)構(gòu)大概是這樣的class DiffHunk: old_start: int old_lines: int new_start: int new_lines: int lines: List[DiffLine] class DiffLine: type: str # add, delete, context content: str old_lineno: Optional[int] new_lineno: Optional[int]這個(gè)結(jié)構(gòu)看起來(lái)簡(jiǎn)單但實(shí)際用起來(lái)很關(guān)鍵。比如后面要做「空指針風(fēng)險(xiǎn)檢測(cè)」就需要知道某一行是新增的還是上下文——只有新增的行才需要報(bào)風(fēng)險(xiǎn)上下文行是歷史代碼報(bào)了也沒(méi)用。注意解析 diff 時(shí)一定要保留原始行號(hào)信息。很多工具為了省事只保留內(nèi)容結(jié)果后面想定位問(wèn)題行號(hào)時(shí)抓瞎。行號(hào)是評(píng)審報(bào)告的核心索引丟了行號(hào)報(bào)告就沒(méi)法直接跳轉(zhuǎn)到代碼位置。2.2 規(guī)則引擎怎么定義「什么是問(wèn)題」規(guī)則引擎是open-code-review的核心。它需要支持幾種類型的規(guī)則第一種是正則規(guī)則最簡(jiǎn)單也最常用。比如檢測(cè)硬編碼密鑰- id: hardcoded-secret pattern: (?i)(password|secret|token|api_key)\s*\s*[][^][] severity: high message: 疑似硬編碼密鑰建議改用環(huán)境變量或配置中心 languages: [python, javascript, java, go]第二種是AST 規(guī)則需要解析語(yǔ)法樹(shù)。比如檢測(cè)「異常吞沒(méi)」——catch 塊里什么都不做# 偽代碼示意 def check_empty_catch(node): if isinstance(node, ast.ExceptHandler): if len(node.body) 1 and isinstance(node.body[0], ast.Pass): report(node, 空的異常處理塊建議至少記錄日志)第三種是跨行規(guī)則需要看多行上下文。比如檢測(cè)「資源未釋放」——打開(kāi)了文件但沒(méi)有對(duì)應(yīng)的 close# 檢測(cè)模式open() 調(diào)用后在同一個(gè)函數(shù)作用域內(nèi)沒(méi)有 close() 或 with 語(yǔ)句規(guī)則引擎的設(shè)計(jì)要點(diǎn)是可擴(kuò)展。不同團(tuán)隊(duì)有不同的規(guī)范硬編碼規(guī)則肯定不行。open-code-review的做法是把規(guī)則定義成 YAML 文件放在.open-code-review/rules/目錄下工具啟動(dòng)時(shí)自動(dòng)加載。這樣團(tuán)隊(duì)可以自己加規(guī)則也可以覆蓋默認(rèn)規(guī)則。我個(gè)人的經(jīng)驗(yàn)是規(guī)則不要一開(kāi)始就寫太多。先上 5-10 條最關(guān)鍵的跑一段時(shí)間看看誤報(bào)率。誤報(bào)率高的規(guī)則要么調(diào)精確要么直接刪掉。規(guī)則太多、誤報(bào)太多評(píng)審員就會(huì)開(kāi)始忽略所有提示工具就廢了。2.3 報(bào)告生成器怎么讓評(píng)審員愿意看報(bào)告生成器決定了工具的「用戶體驗(yàn)」。我見(jiàn)過(guò)太多工具分析能力很強(qiáng)但輸出一份幾百行的 JSON根本沒(méi)人看。open-code-review的報(bào)告設(shè)計(jì)遵循三個(gè)原則第一按文件分組按行號(hào)排序。評(píng)審員看代碼是按文件看的報(bào)告也應(yīng)該按文件組織。每個(gè)文件下面問(wèn)題按行號(hào)從小到大排列方便對(duì)照代碼。第二每條問(wèn)題必須包含「位置、嚴(yán)重程度、說(shuō)明、建議」四要素。位置要精確到行號(hào)嚴(yán)重程度分 high/medium/low 三檔說(shuō)明要講清楚「為什么這是問(wèn)題」建議要給出「怎么改」。第三支持多種輸出格式。命令行輸出用彩色文本方便本地跑CI 環(huán)境輸出 Markdown方便貼到 MR 評(píng)論里還支持 JSON 輸出方便其他工具集成。一個(gè)典型的報(bào)告片段長(zhǎng)這樣## src/service/user.py ### L45 [HIGH] 疑似空指針風(fēng)險(xiǎn) python user self.repo.find_by_id(user_id) return user.name # user 可能為 None建議在調(diào)用.name前增加 None 檢查或使用user?.name如果語(yǔ)言支持。L78 [MEDIUM] 硬編碼超時(shí)時(shí)間response requests.get(url, timeout30)建議將超時(shí)時(shí)間提取到配置文件便于不同環(huán)境調(diào)整。這種格式的好處是評(píng)審員可以直接把這段貼到 MR 評(píng)論里不需要再手動(dòng)整理。 ## 3. 從零搭建 open-code-review 的完整實(shí)操 ### 3.1 環(huán)境準(zhǔn)備與依賴安裝 open-code-review 本身是一個(gè) Python 項(xiàng)目但它的設(shè)計(jì)目標(biāo)是「語(yǔ)言無(wú)關(guān)」——也就是說(shuō)它可以用在任何語(yǔ)言的代碼庫(kù)上。核心依賴只有幾個(gè) - Python 3.9運(yùn)行時(shí) - pyyaml解析規(guī)則文件 - click命令行界面 - rich終端彩色輸出 - tree-sitter可選用于 AST 分析 安裝方式有兩種。如果你只是想用直接 pip 安裝 bash pip install open-code-review如果你想改代碼或者加規(guī)則建議從源碼安裝git clone https://github.com/your-org/open-code-review.git cd open-code-review pip install -e .[dev]-e是 editable 模式改代碼后不需要重新安裝。[dev]會(huì)額外安裝測(cè)試和 lint 工具。提示如果你在 CI 環(huán)境里用建議固定版本號(hào)比如pip install open-code-review1.2.3。我遇到過(guò)因?yàn)樽詣?dòng)升級(jí)到新版本導(dǎo)致規(guī)則行為變化CI 突然掛掉的情況。3.2 配置文件怎么寫open-code-review的配置文件是.open-code-review.yml放在項(xiàng)目根目錄。一個(gè)完整的配置大概長(zhǎng)這樣version: 1 # 要分析的文件類型 include: - **/*.py - **/*.js - **/*.ts - **/*.go - **/*.java # 要排除的目錄 exclude: - **/node_modules/** - **/vendor/** - **/*.min.js - **/test_fixtures/** # 規(guī)則配置 rules: # 啟用默認(rèn)規(guī)則 default: true # 覆蓋某條默認(rèn)規(guī)則的嚴(yán)重程度 overrides: hardcoded-secret: severity: critical long-function: severity: low max_lines: 80 # 自定義參數(shù) # 禁用某條規(guī)則 disabled: - todo-comment # 自定義規(guī)則目錄 custom_dir: .open-code-review/rules # 輸出配置 output: format: markdown # markdown | text | json group_by: file # file | severity | rule max_issues: 100 # 最多輸出多少條防止刷屏 # 忽略配置 ignore: # 忽略特定文件的特定規(guī)則 - file: src/legacy/** rules: [*] # 忽略所有規(guī)則 - file: src/generated/** rules: [naming-convention]這個(gè)配置的每個(gè)字段都有講究。include和exclude決定了分析范圍配錯(cuò)了要么漏分析要么分析一堆無(wú)關(guān)文件。rules.overrides允許你調(diào)整默認(rèn)規(guī)則的嚴(yán)重程度——比如你們團(tuán)隊(duì)覺(jué)得「函數(shù)太長(zhǎng)」不是大問(wèn)題就可以調(diào)成 low。ignore是逃生通道歷史遺留代碼或者自動(dòng)生成的代碼直接忽略掉不要浪費(fèi)評(píng)審員的注意力。3.3 跑一次完整的評(píng)審配置寫好后跑評(píng)審就一行命令ocr review --base main --head feature-branch這個(gè)命令的意思是對(duì)比main分支和feature-branch分支的差異對(duì)差異部分跑評(píng)審。輸出會(huì)直接打印到終端。如果你想集成到 CI 里可以用ocr review --base $CI_MERGE_REQUEST_TARGET_BRANCH --head $CI_COMMIT_SHA --format markdown --output review.md然后把review.md的內(nèi)容貼到 MR 評(píng)論里。我實(shí)測(cè)下來(lái)一個(gè)中等規(guī)模的項(xiàng)目大概 5 萬(wàn)行代碼一次評(píng)審的耗時(shí)在 3-5 秒左右。這個(gè)速度是可以接受的不會(huì)拖慢 CI 流程。3.4 自定義規(guī)則的寫法默認(rèn)規(guī)則覆蓋的是通用場(chǎng)景但每個(gè)團(tuán)隊(duì)都有自己的規(guī)范。寫自定義規(guī)則是open-code-review最有價(jià)值的部分。自定義規(guī)則放在.open-code-review/rules/目錄下每個(gè)規(guī)則一個(gè) YAML 文件。比如你們團(tuán)隊(duì)規(guī)定「所有數(shù)據(jù)庫(kù)查詢必須加超時(shí)」可以寫一條規(guī)則id: db-query-timeout description: 數(shù)據(jù)庫(kù)查詢必須設(shè)置超時(shí)時(shí)間 severity: high languages: [python] pattern: \.(query|execute|fetchall|fetchone)\s*\( negative_pattern: timeout\s* message: | 檢測(cè)到數(shù)據(jù)庫(kù)查詢調(diào)用但未設(shè)置 timeout 參數(shù)。 建議所有數(shù)據(jù)庫(kù)查詢都應(yīng)設(shè)置超時(shí)避免慢查詢拖垮服務(wù)。 示例cursor.execute(sql, timeout5)這條規(guī)則的意思是如果匹配到.query(或.execute(等調(diào)用但同一行或附近沒(méi)有timeout就報(bào)問(wèn)題。更復(fù)雜的規(guī)則可以用 AST。比如檢測(cè)「函數(shù)參數(shù)超過(guò) 5 個(gè)」id: too-many-params description: 函數(shù)參數(shù)過(guò)多建議重構(gòu) severity: medium languages: [python] ast_check: function_params_count 5 message: 函數(shù)參數(shù)超過(guò) 5 個(gè)考慮用參數(shù)對(duì)象或拆分函數(shù)AST 規(guī)則的寫法需要參考o(jì)pen-code-review的 AST 節(jié)點(diǎn)定義文檔這里不展開(kāi)。注意自定義規(guī)則一定要寫測(cè)試。我見(jiàn)過(guò)太多團(tuán)隊(duì)加了一條規(guī)則結(jié)果誤報(bào)率極高最后不得不刪掉。寫規(guī)則時(shí)準(zhǔn)備幾個(gè)正例和反例跑一遍確認(rèn)行為符合預(yù)期。4. 常見(jiàn)問(wèn)題排查與實(shí)戰(zhàn)避坑指南4.1 誤報(bào)太多怎么辦這是最常見(jiàn)的問(wèn)題。工具剛上線時(shí)評(píng)審員看到一堆提示第一反應(yīng)是「這工具在瞎報(bào)」。處理誤報(bào)有幾個(gè)層次第一層調(diào)整規(guī)則參數(shù)。很多規(guī)則有可調(diào)參數(shù)比如「函數(shù)太長(zhǎng)」的閾值、「圈復(fù)雜度」的上限。默認(rèn)值可能不適合你的項(xiàng)目調(diào)一調(diào)就能大幅降低誤報(bào)。第二層用 ignore 配置排除。如果某個(gè)目錄的代碼就是不符合規(guī)范比如歷史遺留代碼直接在配置里忽略掉不要試圖修復(fù)所有歷史問(wèn)題。第三層改進(jìn)規(guī)則本身。如果一條規(guī)則誤報(bào)率超過(guò) 30%說(shuō)明規(guī)則寫得不夠精確。比如「硬編碼密鑰」的正則如果太寬泛會(huì)把password_field user_password這種也報(bào)出來(lái)。這時(shí)候需要加 negative pattern 或者改用 AST 檢測(cè)。我個(gè)人的經(jīng)驗(yàn)是新規(guī)則上線前先在歷史 MR 上跑一遍統(tǒng)計(jì)誤報(bào)率。誤報(bào)率低于 10% 才允許上線。這個(gè)流程看起來(lái)麻煩但能避免工具被評(píng)審員集體抵制。4.2 大 MR 怎么處理一個(gè) MR 改了 200 個(gè)文件、5000 行代碼工具跑出來(lái)的報(bào)告可能幾百條。評(píng)審員根本看不完。處理策略是分級(jí)輸出。open-code-review支持max_issues配置但簡(jiǎn)單截?cái)嗖皇呛棉k法。更好的做法是按嚴(yán)重程度分組high 的問(wèn)題全部輸出medium 和 low 各輸出前 N 條。按文件分組每個(gè)文件最多輸出 M 條超出部分折疊。提供一個(gè)「摘要」視圖只顯示每個(gè)文件的 high 問(wèn)題數(shù)量評(píng)審員可以按需展開(kāi)。另外大 MR 本身就是個(gè)問(wèn)題。我通常建議團(tuán)隊(duì)把 MR 控制在 400 行以內(nèi)超過(guò)就拆分。工具可以在 MR 超過(guò)閾值時(shí)給出提示「本次改動(dòng) 1200 行建議拆分為多個(gè) MR」。4.3 怎么和現(xiàn)有 CI 集成open-code-review設(shè)計(jì)上是 CI 友好的。它不依賴任何特定 CI 平臺(tái)只要有命令行環(huán)境就能跑。集成方式取決于你的 CI 平臺(tái)CI 平臺(tái)集成方式注意事項(xiàng)GitLab CI在.gitlab-ci.yml加一個(gè) job調(diào)用ocr review需要設(shè)置GIT_DEPTH足夠大否則拿不到 base 分支GitHub Actions用actions/checkout拉代碼然后跑ocr review需要fetch-depth: 0才能拿到完整歷史Jenkins在 pipeline 里加一個(gè) stage確保工作空間有 base 分支的引用本地 pre-push hook在.git/hooks/pre-push里調(diào)用耗時(shí)太長(zhǎng)會(huì)影響推送體驗(yàn)建議只跑 high 級(jí)別規(guī)則集成時(shí)的一個(gè)關(guān)鍵問(wèn)題是退出碼。open-code-review默認(rèn)在發(fā)現(xiàn) high 級(jí)別問(wèn)題時(shí)返回非零退出碼這樣 CI 會(huì)標(biāo)記為失敗。但有些團(tuán)隊(duì)希望「只提示不阻斷」可以通過(guò)--exit-zero參數(shù)讓工具始終返回 0。4.4 性能優(yōu)化大項(xiàng)目怎么跑得快項(xiàng)目大了之后全量分析會(huì)很慢。優(yōu)化手段有幾個(gè)增量分析。只分析 diff 涉及的文件而不是全量代碼。這是open-code-review的默認(rèn)行為但需要確保 diff 解析正確。緩存。對(duì)沒(méi)有改動(dòng)的文件復(fù)用上次的分析結(jié)果。緩存 key 可以用文件內(nèi)容的 hash。這個(gè)功能需要額外配置默認(rèn)關(guān)閉。并行。多文件分析可以并行跑。open-code-review支持--jobs N參數(shù)N 建議設(shè)置為 CPU 核心數(shù)。規(guī)則裁剪。不是所有規(guī)則都需要在 CI 里跑?？梢园岩?guī)則分成「快速規(guī)則」和「深度規(guī)則」CI 里只跑快速規(guī)則深度規(guī)則在 nightly build 里跑。我實(shí)測(cè)過(guò)一個(gè) 20 萬(wàn)行的項(xiàng)目全量分析大概 30 秒增量分析改動(dòng) 10 個(gè)文件大概 2 秒。這個(gè)性能是可以接受的。4.5 常見(jiàn)問(wèn)題速查表問(wèn)題現(xiàn)象可能原因解決方法報(bào)告里沒(méi)有新增行的提示diff 解析失敗可能 base 分支引用不對(duì)檢查--base參數(shù)確保分支存在規(guī)則不生效規(guī)則文件格式錯(cuò)誤或路徑不對(duì)用ocr rules list查看已加載的規(guī)則誤報(bào)率高規(guī)則太寬泛調(diào)整 pattern 或加 negative_patternCI 里跑報(bào)錯(cuò)缺少依賴或 Python 版本不對(duì)檢查 CI 環(huán)境的 Python 版本和依賴安裝輸出亂碼終端不支持 UTF-8設(shè)置PYTHONIOENCODINGutf-8分析速度慢全量分析或規(guī)則太多啟用增量分析裁剪規(guī)則5. 把 open-code-review 用出效果的幾個(gè)關(guān)鍵認(rèn)知5.1 工具是輔助不是替代我見(jiàn)過(guò)一些團(tuán)隊(duì)上了代碼評(píng)審工具后就指望工具能發(fā)現(xiàn)所有問(wèn)題人工評(píng)審變得敷衍。這是本末倒置。open-code-review能發(fā)現(xiàn)的是「模式化的問(wèn)題」——空指針、硬編碼、命名不規(guī)范。但真正重要的評(píng)審內(nèi)容——這個(gè)設(shè)計(jì)是否合理、這個(gè)抽象是否過(guò)度、這個(gè)接口是否穩(wěn)定——工具永遠(yuǎn)發(fā)現(xiàn)不了。正確的用法是工具跑完后評(píng)審員先看工具報(bào)告把機(jī)械性問(wèn)題確認(rèn)掉然后帶著「工具沒(méi)發(fā)現(xiàn)什么」的視角去看代碼。工具沒(méi)報(bào)問(wèn)題的地方不代表沒(méi)問(wèn)題可能只是規(guī)則沒(méi)覆蓋到。評(píng)審員的精力應(yīng)該花在這些地方。5.2 規(guī)則要跟著團(tuán)隊(duì)成長(zhǎng)團(tuán)隊(duì)剛起步時(shí)規(guī)則可以少一點(diǎn)只覆蓋最關(guān)鍵的幾條。隨著團(tuán)隊(duì)變大、代碼變多規(guī)則也要逐步增加。但增加規(guī)則不是目的減少評(píng)審中的重復(fù)討論才是目的。我通常建議團(tuán)隊(duì)每季度回顧一次規(guī)則哪些規(guī)則從來(lái)沒(méi)觸發(fā)過(guò)可能太寬松哪些規(guī)則經(jīng)常被忽略可能誤報(bào)太多哪些新問(wèn)題反復(fù)出現(xiàn)需要加規(guī)則。這個(gè)回顧過(guò)程本身就是團(tuán)隊(duì)技術(shù)規(guī)范的一次對(duì)齊。5.3 報(bào)告的可操作性比全面性更重要一份報(bào)告如果列了 100 條問(wèn)題但評(píng)審員一條都不想改那這份報(bào)告就是失敗的。好的報(bào)告應(yīng)該是每條問(wèn)題都讓評(píng)審員覺(jué)得「確實(shí)該改」。為了做到這一點(diǎn)報(bào)告里的每條問(wèn)題都要有明確的「行動(dòng)建議」。不要只說(shuō)「這里有風(fēng)險(xiǎn)」要說(shuō)「這里有風(fēng)險(xiǎn)建議改成這樣」。評(píng)審員看到建議后如果認(rèn)同直接改如果不認(rèn)同標(biāo)記「已知悉」。這個(gè)交互過(guò)程才是工具的價(jià)值所在。5.4 不要追求零誤報(bào)零誤報(bào)是個(gè)不可能的目標(biāo)。代碼評(píng)審本身就有主觀性同一條代碼有人覺(jué)得沒(méi)問(wèn)題有人覺(jué)得有問(wèn)題。工具能做的是把「大概率有問(wèn)題」的地方標(biāo)出來(lái)讓評(píng)審員快速判斷。我個(gè)人的標(biāo)準(zhǔn)是誤報(bào)率控制在 15% 以內(nèi)漏報(bào)率控制在 30% 以內(nèi)。這個(gè)標(biāo)準(zhǔn)下工具是有用的但不會(huì)讓評(píng)審員覺(jué)得煩。追求更低的誤報(bào)率往往意味著規(guī)則變得很窄漏報(bào)率會(huì)上升反而失去了工具的意義。5.5 從「檢查」到「教育」open-code-review還有一個(gè)隱性價(jià)值它是一份活的代碼規(guī)范文檔。新加入團(tuán)隊(duì)的開(kāi)發(fā)者跑一次評(píng)審看到工具報(bào)出的問(wèn)題就知道團(tuán)隊(duì)在意什么。這比扔一份幾十頁(yè)的規(guī)范文檔有效得多。我通常建議團(tuán)隊(duì)把工具報(bào)告里的「建議」寫得詳細(xì)一點(diǎn)最好帶上示例代碼。這樣新人在改問(wèn)題的同時(shí)也學(xué)到了團(tuán)隊(duì)的編碼習(xí)慣。時(shí)間長(zhǎng)了很多問(wèn)題在寫代碼時(shí)就被避免了工具報(bào)出的問(wèn)題會(huì)越來(lái)越少——這才是工具成功的標(biāo)志。最后分享一個(gè)我自己的小習(xí)慣每次評(píng)審?fù)晡視?huì)把工具報(bào)出的、但評(píng)審員選擇「已知悉」的問(wèn)題記下來(lái)。如果同一個(gè)模式被「已知悉」超過(guò)三次說(shuō)明要么規(guī)則有問(wèn)題要么團(tuán)隊(duì)規(guī)范需要調(diào)整。這個(gè)反饋循環(huán)是讓工具越用越順手的關(guān)鍵。