Learning Code Review & Commit Message with Google
- 1. Learning Code Review & Commit Message with Google Sharing by Kira
- 2. Why Code Review exists? The main goal of Code Review is to improve code quality ✅ Good functionality & Code quality is not reducing (except emergency) ✅ There is no “prefect” code, only “better” code ✅ Good for developers to learn from each other and increase knowledge transfer ❌ High standard => No progress on tasks Developers are disincentivized to make improvements
- 3. What is Emergency Situation? Emergency CL should be a small change ✅ Fix a bug significantly affecting users in production ✅ Handle a pressing legal issue ✅ Close a major security hole ❌ A manager says that this review has to be complete today ❌ It is the end of the day on a Friday and it would just be great to get this CL in before the developer leaves for the weekend ❌ The developer has worked on a feature for a very long time and they really want to get the CL in
- 5. ⧭ The principle of Code Review ✅ Technical facts and data overrule opinions and personal preferences 事實和數據 >個人偏好 ✅ Consistency : follow coding style guide > follow code base > personal style 文件 > 專案程式碼 > 個人風格 🚩 發生意見衝突時Conflict of opinion come to consensus -> face-to-face meeting -> broader team discussion
- 6. What to look for in a code review (1) ● Design 設計 ○ 程式碼運行方式合理 - Do the interactions of varios pieces of code in the CL make sense? ○ 與既有專案的整合 - Does it integrate well with the rest of your system? ○ 正確的時間點 - Is now a good time to add this functionality? ● Functionality 功能 ○ 達到預期目標 - Does this CL do what the developer intended? ○ 對使用者帶來好處 - Is what the developer intended good for the other developers and end-users? ○ 考量極端案例，尋找併發性問題 - Think about edge cases and look for concurrency problems ○ 驗證修改，檢查會對使用者造成影響的行為 - Validate the CL and check user-facing impact behaviors ex : UI change ○ 確保沒有因平行運算造成 deadlock 或 race condition - No parallel programming cause deadlocks or race conditions ● Complexity 複雜度 ○ 閱讀程式碼者可以很快理解 - Code can be understood quickly by code readers ■ Developers are not likely to introduce bugs when they try to call or modify this code ○ 沒有過度設計 - No over engineering
- 7. What to look for in a code review (2) ● Test 測試 ○ 依據改動適當要求加入單元測試、整合測試或 end-to-end 測試 - Ask for unit, integration, or end-to-end tests as appropriate for the change ○ 相同 CL 內必須加入測試(緊急修復除外)，並視為產品的一部分 - Test should be added in the same CL as the production code unless the CL is handling an emergency ○ 確保測試是正確的、合理且有用的 - Make sure that the tests are correct, sensible, and useful ■ 當程式碼修改時，測試是否會失敗- Will the tests actually fail when the code is broken? ■ 每個測試都使用簡單且有效的斷言- Does each test make simple and usefule assertion? ■ 測試是否在不同測試方法之間分開- Are the tests separated appropriately between different test methods? ● Naming 命名 ○ 良好的命名 Good Name ■ 明確表達且容易閱讀 - A good name is long enough to fully communicate what the item is or does, without being so long that is becomes hard to read ● Comments 注釋 ○ 解釋 why 而非 what - Explain why some code exists, instead of what some code is doing ○ 清楚好懂的註解 - Did developer write clear and understandable comments ○ 註解是有用的 - Are all of the comments actually necessary 🙋 什麼樣的情況下需要寫註釋？ 註釋使用什麼語言？
- 8. What to look for in a code review (3) ● Style 樣式 ○ 遵守 style guide 保持一致性 - Make sure the CL follows the appropriate style guides ○ 若有不在 style guide 中的樣式建議，加上”非必要”之類的文字 - If you want to improve some style point that isn’t in the style guide, prefix your comment with “Nit:” to let developer know that it’s a nit pick. ○ 補充：善用 linter 工具 ● Documentation 文件 ○ 清楚的文件 clear documentation ■ 倘若CL更改了使用者建構、測試、互動或發布的行為，需檢 查相關文件是否同步更新- If CL changes how users build, test, interact with, or lease code, the associated documentation should also be updated. ■ 倘若CL刪除或棄用程式碼，考慮是否刪除文件- If CL deletes or deprecates code, consider whether the documentation should be deleted. ■ 倘若缺少文件，則要求補上- If documentation is missing, ask for it ● Every Line 審視每一行程式碼 ○ 用不同審視角度減少盲點 Think about the CL in different( board/narrow) context ■ 一般而言，審視每一行指定審視的程式碼; 有些大型資料結構或資料文件等可以快速掃過 - In general, look ar every line of code that you have been assigned to review. ■ 倘若程式碼太難閱讀且影響review時間，請開發者調整，並等他們把 CL變得清晰易懂後再進行審 查 - If it’s too hard for you to read the code and this is slowing down the review, then you should tell developer and wait for them to clarify before you try to review it. ■ 倘若你不需要審視每一行，則標註你已經審視的部分 - If it doesn’t make sense for you to review every line, please not in a comment which parts you reviewed.
- 9. The process & speed of code review Process : Direction > Main feature > Details Step 1 - Take a broad view of the change Step 2 - Examine the main parts Step 3 - Look through the rest of code in an appropriate sequence Respond speed : One business day is the maximum ● A typical CL should get multiple rounds of review(if needed) within a single day ● If you are in the middle of a focused task, don’t interrupt yourself to do a code review. A break point of your work could be a good time. ● Too busy to do full review => tell when you will review, suggest other reviewers, or provide some initial broad comments 🙋 身為審查者，你的審查習慣是什麼？
- 10. ⧭ How to write code review comments ● Courtesy and respect 保持友善和尊重 Make comments about the “code”, not the “developer” ● Concrete feedback & Explain why 具體回饋及建議原因 line of code, direction(ex: syntax, design patterm) , reference articles etc. ✅ 為什麼你要在這邊使用Multiple Threads？它顯然沒有任何效益 ❎ 這裡增加了系統複雜度，但沒有效能上的效益。因此應將程式碼改為 Single Thread，而非使用 Multiple Threads ● Consider time constraints 考量時間限制 If the changes need much time to improve, it is better to open a new task ● Leave comment with must/nice to have 區分必要和非必要修改 Google style - use prefix Nit: before comment (ex: Nit: remove whitespace) ● Don’t hesitate to leave compliments when you see a good practice 不吝於讚美和鼓勵
- 11. As a developer
- 12. How to leave a good commit message ● Commit message is a public record of what change is being made and why it was made. It’s permenent and will possibily be read by many developers in the future😱 ● Commit Message includes two parts: ○ 標題 Subject ■ 摘要變更內容 Short summary of what is being done ■ 簡短清晰、直指重點Short, clear, and to the point ■ 完整的命令句(祈使句) Complete sentence, written as though it was an order Ex: ✅ Delete the FizzBuzz RPC and replace it with the new system ❎ Deleting the FizzBuzz RPC and replacing it with the new system ■ 其他：限制50字、首字大寫等(Chris Beams)、加上 type 或 scope ○ 身體 Body ■ 描述更詳細的資訊 ■ 包含解決的問題、為何使用此解法、此解法的優缺點等 Include a brief description of the problem that’s being solved, and why this is the best approach ■ 若相關，可附上相關設計文件、任務編號、效能測試結果等 If relevant, include background information such as bug numbers, benchmark results, and links to design documents.
- 13. Examples of Subject Bad ones ❌ Fix bug / typo - 沒有說明什麼bug/typo、如何修復 ❌ Update languageBar package version - 沒有版號 ❌ Moving code from A to B - 沒有使用命令句、哪一段 code ❌ kill weird URLs - 首字大小寫一致、wield URLs 語意不清 Better ones ✅ Fix typo (displya → display) ✅ Update languageBar package version from 1.0.2 to 1.0.3 ✅ Move signIn button from HomePage to SignIn page ✅ Remove unused urls in HomePage
- 14. A better subject with type and scope Types ● feat: 新增/修改功能 (feature) ● fix: 修補 bug (bug fix) ● docs: 文件 (documentation) ● style: 格式 ● refactor: 重構 ● perf: 改善效能(performance) ● test: 增加/修改測試 ● chore: 建構程序或輔助工具的變動(ex: 更新版號、CICD) Reference : Gitmoji Conventional Commits Automation: commitlint commitlint-jira
- 15. Small tips 1. 拆分成小的 Commit : A CL is one self-contained change 一個 commit 處理一個改動 2. 推上遠端分支前，先整理一下Commits (編輯/合併/拆分) git rebase <hash> -i 3. Merge 到主分支的時候可以做Merge Squash，讓主分支的 Commit 更乾淨
- 16. Reference Google - How To Do A Code Review (EN) Google - The CL Author’s Guide (EN) Google - Style Guide (EN) 跟 Google 學如何 Code Review (中文) How to Write a Git Commit Message