The CL author’s guide to getting through code review
该文章主要介绍如何做好代码审核工作。主要内容分为如何做好代码记录和如何做好代码审核。本次阅读主要围绕如何做好代码记录。
如何写好修改记录描述
修改记录描述是记录修改什么和修改理由的公开记录。该记录可以用来作为版本控制的一部分。 如果我们所有重要信息都写在代码里面，则很难让其他人去理解修改记录。
第一行
- 简短总结做了什么
- 内容以指令方式展示
- 然后空一行
该内容需要提供足够有效的信息，别人不需要查看完整描述就知道具体修改内容。而且这样也方便别人去查询和做版本控制
主体内容清晰有效
主体内容必须清除表达什么问题被解决，并解决为什么这种是最佳方式。 如果存在什么缺点也需要提出来。如果有关联资料也出提出来，例如Bug的背景，需求设计文档，测试结果等
差的描述例子
- “修复完成”
- “添加补丁”
- “从A到B移动代码”
- “新增便利功能”
好的描述例子
功能性修改
rpc：删除RPC服务器消息空闲列表的大小限制
服务器（例如FizzBuzz）有很非常大消息，将空闲列表变更大and新增一个goroutine
（Go语言技术）用于释放空闲列表（随着时间推移逐渐释放）。这样最终可以释放所有空闲列表
第一行描述决定完成内容。其他内容描述问题如何解决，为什么要这么解决以及其他相关的信息。
重构
用计时器去创建一个任务，使用TimeStr和Now方法
在该任务中添加一个Now函数，然后可以移除borglet的getter方法
（该方法仅仅被OOMCandidate调用borglet的Now方法才使用）。
这个可以替换掉Borglet在计时器的方法。
允许任务提供Now方法是为移除对Borglet的依赖。
最终应该将从任务获取Now方法调整为直接使用计时器，但这个只是重构一小步
继续重建Borglet结构是长期目标
该描述中补充该修改方案不是最佳选择，后面给未来重构方案给出的建议。
修改的背景
为status.py创建Python3构建规则
这样允许基于Python3构建规则的使用者可以依赖旁边的构建规整，而不依赖于自己树中的某个位置。
鼓励所有新使用者尽可能使用Python3来替换Python2，大大简化了当前使用的自动构建文件重构工具
该描述给出一些背景资料
精简的修改记录
特征
- 易于快速审核：内容足够精简便于审核人快速审核
- 审核足够彻底：如果进行大量改动，审核人需要阅读大量内容，这样容易导致遗漏部分内容
- 尽可能小引入错误：将改动范围进行缩小，让审核者容易判断是否引入问题
- 节约审核时间：如果记录内容非常多，那么审核人需要花时间来审核，而最后结果拒绝的
- 易于设计：调整小部分代码和设计比调整大部分要容易
- 减少工作的阻塞：只需要提交整体一部分设计，然后可以继续开发其他部分内容
- 便于回滚：每次调整都是设计多个文件和内容，则会使得回滚变得复杂。
合适的大小
一般来说合适大小为一个独立模块修改
- 该修改记录是对一个任务最小调整，这只是某个功能一部分。一般需要于审核者讨论提交大小尺度。
- 审核者需要从修改记录中了解所有修改内容。
- 加入该修改之后，系统依然使用。
- 通过加入APi文件协助审核更好了解功能。
实际上什么是太大，这个确实没有一个很好界限规定。这个需要一定时间去适应，开发者请编写小于自己认为需要编写的记录，而且审核者却很少会抱怨记录内容太少。
大修改情况
以下这几种场景，大修改情况也是可以的
- 可以通过一行修改记录登记删除一个文件
- 有时间可以信任由自动构建工具生成比较大修改
文件拆分 除了独立修改之后情况以外，我们可以将一个修改按照文件进行分组，然后给不同审核者 例如： 部分1：修改协议缓冲区 部分2：修改使用该协议的代码 这样可以分两部分提交，但是需要在修改记录提及另外一个修改记录信息。这样确保审核者了解使用上下文
相关测试代码
需要避免将相关测试代码分离提交；如果类似重构情况，可以将独立测试代码单独提交一个记录，里面需要包含内容如下： 1、使用新测试代码验证之前提交的代码 2、重构测试代码（辅助函数） 3、引入更大的测试框架代码（集成测试）
如何处理审核评论
避免情绪化审核
代码审核的目的就是提交代码和产品的质量。永远不再在愤怒情况之下完成代码评论。
修复代码
如果审核人无法了解开发者的代码，开发者需要立刻说明自己的代码。此外需要请添加代码注释，以说明该代码的原因。请不要只在代码审核工具中回复，这样后续开发者也不看到这写内容
