general-codereview
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseGeneral Code Review Skill
通用代码审查技能
A comprehensive code review methodology based on Google's engineering practices. Follow these 5 steps to perform effective and thorough code reviews.
这是基于谷歌工程实践的一套全面的代码审查方法论。遵循以下5个步骤，即可开展高效且全面的代码审查。
Step 1: Pre-screen
步骤1：预筛选
Before diving into the code, perform a quick pre-screening:
在深入查看代码之前，先进行快速预筛选：
Check Size
检查变更规模
- Reasonable size: A change list of ~300 lines of code is typically reasonable
- Too large: Larger CLs should be strongly discouraged unless necessary
- Leave a comment asking if the CL can be broken down into smaller, logically complete parts
- Ask for the reason if breaking down is not possible
- Small is OK: Even single-line changes are fine as long as they are logically complete
- 合理规模：通常约300行代码的change list是合理的
- 规模过大：应强烈建议拆分规模过大的CL（变更列表），除非有必要
- 留下评论询问是否可以将该CL拆分为更小的、逻辑完整的部分
- 如果无法拆分，询问原因
- 小规模可行：只要逻辑完整，即使是单行变更也没问题
Verify You're the Right Reviewer
确认自己是合适的审查者
Ask yourself:
- Am I familiar enough with this code area?
- Do I understand the language, environment, and context?
- Is there someone better suited to review this?
If you're not the ideal reviewer but no one else is available, prepare to quickly learn about the unfamiliar aspects.
自问：
- 我对这个代码领域足够熟悉吗？
- 我是否理解相关的编程语言、环境和上下文？
- 是否有更适合审查该代码的人选？
如果你不是理想的审查者，但没有其他合适人选，请准备快速学习不熟悉的相关内容。
Step 2: Understand
步骤2：理解变更
After pre-screening, focus on understanding the change from the author's perspective.
预筛选完成后，从代码作者的角度聚焦理解变更内容。
Purpose
变更目的
Ask: "Do I know the overall purpose of this CL?"
- The purpose should be clearly stated in the CL description
- If unclear, request clarification
- Even self-explanatory code needs a clear description for future maintainers
- Remember: even the author may need to refer back to the description later
自问：“我是否清楚这个CL的整体目的？”
- 变更目的应在CL描述中明确说明
- 如果不清晰，请求作者澄清
- 即使是自解释的代码，也需要清晰的描述以便未来维护人员理解
- 记住：即使是作者本人，日后也可能需要参考该描述
Workflow Context
工作流上下文
Ask: "Was I expecting this CL? Does it match my expectations?"
Consider:
- Is this CL part of a larger project or design doc?
- Does it align with the task distribution and design documentation?
- Are there dependencies mentioned?
- Other changes that need to happen before this CL can function
- Other CLs that are blocked by this change
自问：“我是否预期到这个CL？它符合我的预期吗？”
考虑：
- 这个CL是否属于某个更大的项目或设计文档的一部分？
- 它是否与任务分配和设计文档一致？
- 是否提到了依赖关系？
- 该CL正常运行前需要完成的其他变更
- 被该变更阻塞的其他CL
Design Decisions
设计决策
Verify that important design decisions are:
- Documented in the code description
- Explained with rationale when non-obvious
确认重要的设计决策：
- 已记录在代码描述中
- 对于非显而易见的决策，已说明理由
Step 3: Verify
步骤3：验证实现
Now verify the implementation matches the stated intent.
现在验证实现是否符合所述意图。
Code-Description Alignment
代码与描述一致性
- Verify the code does what the description says
- Flag any discrepancies between stated purpose and actual implementation
- 验证代码是否实现了描述中所说的功能
- 标记出所述目的与实际实现之间的任何差异
Test Coverage
测试覆盖
Verify relevant tests exist for:
| Category | What to Check |
|---|---|
| Design decisions | Tests that validate key architectural choices |
| Important defaults | Tests for default values and their behavior |
| Complex logic | Tests for intricate algorithms or business logic |
| Edge cases | Zero, null, empty, boundary conditions, if-statement edges |
验证是否存在针对以下类别的相关测试：
| 类别 | 检查内容 |
|---|---|
| 设计决策 | 验证关键架构选择的测试 |
| 重要默认值 | 针对默认值及其行为的测试 |
| 复杂逻辑 | 针对复杂算法或业务逻辑的测试 |
| 边缘情况 | 零值、空值、边界条件、分支语句边缘情况 |
Step 4: Optimize
步骤4：优化代码
Look for opportunities to improve the code's efficiency and maintainability.
寻找提升代码效率和可维护性的机会。
Logic Optimization
逻辑优化
- Can the algorithm be simplified?
- Are there unnecessary computations?
- Is the control flow optimal?
- 算法是否可以简化？
- 是否存在不必要的计算？
- 控制流是否最优？
Library Usage
库的使用
- Is the best library being used for this task?
- Are there more appropriate or efficient alternatives?
- Is the library being used correctly and efficiently?
- 是否使用了最适合该任务的库？
- 是否有更合适或更高效的替代方案？
- 库的使用是否正确且高效？
Step 5: Check Style
步骤5：检查代码风格
Final pass for code style and conventions.
最后检查代码风格和规范。
Style Checklist
风格检查清单
- Follows project/team coding standards
- Consistent naming conventions
- Proper formatting and indentation
- Clear and helpful comments
- No dead code or debugging artifacts
- 遵循项目/团队编码标准
- 命名约定一致
- 格式和缩进规范
- 注释清晰且有用
- 无死代码或调试残留
Quick Reference Checklist
快速参考清单
□ Pre-screen
□ Size reasonable (~300 lines)?
□ Am I the right reviewer?
□ Understand
□ Purpose clear in description?
□ Expected in current workflow?
□ Design decisions documented?
□ Verify
□ Code matches description?
□ Tests cover design decisions?
□ Tests cover defaults and edge cases?
□ Optimize
□ Logic optimizable?
□ Library choices optimal?
□ Check
□ Style guidelines followed?Acknowledgment: This methodology is based on reflections from working at Google, with thanks to mentors and teammates who helped improve these code review skills.
□ Pre-screen
□ Size reasonable (~300 lines)?
□ Am I the right reviewer?
□ Understand
□ Purpose clear in description?
□ Expected in current workflow?
□ Design decisions documented?
□ Verify
□ Code matches description?
□ Tests cover design decisions?
□ Tests cover defaults and edge cases?
□ Optimize
□ Logic optimizable?
□ Library choices optimal?
□ Check
□ Style guidelines followed?致谢：本方法论基于在谷歌工作的经验总结，感谢帮助我提升代码审查技能的导师和同事。