# Code Review 101 --- ## Modern Code Review: A Case Study at Google - 從 12 個面談者以及 44 位問卷受訪者，還有從 9 mil 個 reviewed changes 的 review logs 的分析整理而成。 - Google 在很早期便導入 code review 的文化，code review 的流程也在數十年的過程中持續迭代進化，已經被超過兩萬五千名開發者參與，每個工作天產出超過兩萬批 code changes 來自分布在數十個環繞全球的辦公室。 --- ### Convergent Practice - Contemporary peer review follows a light weight, flexible process. - Reivews happen early, quickly, and frequently. - Change sizes are small - Two reviewers find an optimal numbers of defects - Review has changed from a defect finding activity to a group problem solving activity --- ### Code review four key themes - education - maintaining norms - gatekeeping - accident prevention - (tracking history)  --- ### Research Findings - 在 google 的 code review 不只是專注在解決問題這件事，最初導入 code reivew 是要確保可讀性以及可維護性。數十年後，開發者們仍然重視著 code review 在教育層面上的意義。 - 對於 code review 的期待，有時候取決於作者以及 reviewers 之間的職務關係。 ---- - google 的 code review 流程有保持收斂、輕量化、彈性的原則。 相較於其他組織，Ownership 以及可讀性原則在這有更鮮明重要的地位。同時 review tool 能夠提供 reviewer 建議以及靜態檢查。 - 在 google 的 code review 節奏演變的相對快、輕量，在與其他研究結果相比之下。一位 reviewer 在這個環境下已經可以滿足大部分需求，在其他的專案裡可能會需要兩位。 --- ### Review process - Ownership - Readability - Code review flow - Creating - Previewing - Commenting - Addressing Feedback - Approving - Suggesting Reviewers - Code Analysis Results --- ## "Code must act as a teacher for future developers" --- ### Review Analytics --- #### 頻率 - 開發者每周發布 change 數量中位數是 3，80% 的開發者發布不超過 7 個 change。 - reviewer 每周 review change 數量中位數為 4，80% 的 reviewer 不 review 超過 10 個 change。 --- #### 速度 - 開發者在完成整個 review process 所需要等的時間的中位數低於四個小時。 - 在小型的 change 的情況收到第一個 review 回饋等待時間中位數甚至會低於一個小時 - 即使在超級大的 change 也會在約五小時內收到第一個 review 回饋 --- #### Review size(Change scope) - 超過 35% 的 changes 只包含一個檔案，大概 90% 的 changes 修改了少於十個檔案。 - 超過 10% 的 changes 只編輯了一行 code。每個 change 包含的修改行數中位數為 24 行。 --- #### 誰來看，要給多少 comment - 爭議題目 - 有前人研究認為兩位 reviewer 就是最好的數字 - 但在這份研究中發現，Google 有 75% 的 changes 只有一名 reviewer，幾乎沒有超過五個人 review 的 change，中位數的 reviewer 數是一位。 ---- - 一般來說越大的 change 會有越多的 reviewer。 - 超級大的 change 反而通常只需要一兩位 reviewer。 - 前人研究發現越多 active reviewer 會讓 review comment 變多，兩位 reviewer 可以找到足夠多的 bugs。 - 這份研究中，主要會讓 comments 變多的因子是 lines of changes，超過 1250 行的 changes 會有平均 12.5 個 comments。比這還大的 changes 通常會包含一些自動化的 code generation 或是大量的刪除，所以 comments 的數量會開始下降 --- #### 滿意度 - 整體來說在 google 大部分人對於 code review 現況感到滿意 - 在特定的 change 種類底下大家的滿意狀況就有比較多變化，例如極短(一個字或是兩行那種)或是一些為了滿足別的需求而不得不做的 change 的滿意度會相對低 - 關於意見回饋的角度，大部份的人都對自己收到的 review 感到滿意/合宜。 --- #### 花了多少時間 - 每週平均花 3.2 小時 review changes，中位數則是每週 2.6 小時，與前人的研究（每週 6.4 小時）比起來是相對低的。 --- ### Knowledge spreading - 開發者可以在 review 過程中慢慢熟悉更多元件 - 隨著資歷漸長，每個 change 收到的 review comment 會越來越少 - 之前的研究指出：有些 review comment 會被認/標記為沒有幫助，隨著開發者經驗增長給出這些沒幫助 comment 的數量會慢慢降低 - 這些現象都支持 "學習" 在 code review 裡面的價值會隨著時間慢慢顯露 - 我們也能看到隨著年資跟編輯過 review 過的檔案會越來越多。 ----  --- ### Code review breakdown - 理解實做是主要的進入門檻 --- ### 五個對於 review 流程的疑慮和擔憂 - 距離：物理距離、組織距離都一定程度上影響了 review 的速度 - 社交互動：語氣和權力也都會影響 review 流程和成果 - 題目：有些被 review 的主體會讓整體成效變差（ex: design review 無法制式化） - Context：商業或組織上的背景資訊如果沒有陳述清楚容易讓 review 的流程失焦 - 客製化：在 review 工具的運用上常有不同的客製化需求，這會成為推動 review 流程的阻力 --- ### Good practices - reviewer 建議系統可以從你的 change 找出最近剛編輯過類似的區域的 code 的作者進行 review。 - 靜態檢查，可以協助大家完成各種慣例檢查，包含 format, style, security, dependency。同時建立起這些檢查是不是真的有幫上忙的 feedback loop 會是一個能夠維護開發者的信任感的重要流程。 ---- - 將 review tool 的使用不僅僅侷限在 code review，有時候把一個還沒完成的 change 發上 review tool 之後發起討論再決定如何繼續完成，也是一種不錯的用法。 - 回頭檢視 review tool 收集過往的 context，有時也會很有幫助。 --- ## Code Review 原則 - Code reviews 需要在完成 pull request 修改內容後， merge 進主要的 branch 之前完成。 - 盡早發 PR 讓其他人可以掌握開發進度，善用 [WIP] 的標題 - 將你認為熟悉這段程式碼/功能的人列入 review 的 request 列表中。 - Reviewer 自行掌控 code review 的時間點。 ---- - 如果 review 中或 review 完成後有修改程式碼，可以在 pull request 中加入適當提示、送出新的 review request 或用新的 commit 來區分，以免 reviewer 無法分辨新舊修改。 - 若有阻擋後續開發的 pending review 可重複送出 review request，甚至進一步通知，讓 reviewer 知道急迫性。 - Reviewer 以及 committer 需要共同為這個 merged pull request 負責。 --- ## Code Review 的動機 - Committer 因為預期有 reviewer 檢視他的程式碼，所以會更精進自己的實作與技術。 - 讓參與 code review 的成員分享知識，一同成長寫出更好的 code。 - 讓 code base 的設計與 coding style 可以更同步。 - 更早的挑出 bugs, anti-patterns, 以及設計的缺陷，節省後續成本。 --- refs: https://google.github.io/eng-practices/ https://dl.acm.org/doi/pdf/10.1145/3183519.3183525 https://github.com/ryanhanwu/How-To-Ask-Questions-The-Smart-Way https://medium.com/@dan_abramov/asking-good-questions-421f08ee7e5c https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/ICSE202013-codereview.pdf