关于 code reviews 的 why, what and when
为什么需要 code review?
主要目的是为了提升代码质量。为什么可以提升代码质量呢?
1、从代码提交者(即这段代码作者)的角度,考虑到会有一个或者多个 reviewer 在代码提交之后会对自己的代码进行详细的检查,作者会更倾向于编写更整洁的代码,更完善的代码。毕竟所有人(包括工程师)都希望得到他人的认可。
2、code review 即知识分享的过程。而知识分享可以从以下几点帮助到团队的工作:
其他人的代码可能在这个 commit 的基础上进行。
这次的 commit 可能使用到一个算法或者编程技巧,review 的过程就是学习的过程。
reviewer 可能有相关的编程技术或者代码知识,可以帮助改进这次的 commit。
互动和沟通的过程,可以加强团队成员之间的交流。
3、维持工程的一致性。这可以是代码更容易理解和阅读,也可以有效的预防 bug,当有新同学加入的时候,也可以更快的投入到项目中。
4、从旁观者的角度,可以更容易的发现一些意外错误(譬如拼写错误)或者结构错误(逻辑或算法错误,性能或架构问题)等。
5、安全性问题。有些代码甚至需要有专门的安全审查员。
具体 review 些什么东西?
是每一个合到主分支的提交都需要 review,还是设置某一个阈值,在此阈值下的 commit 不需要 code review?需要在时间成本和代码质量之间权衡。
观点:即使是团队中级别最高的人员提交的代码,也需要进行 code review。假如提交的代码完美无瑕,刚好是团队成员学习的好机会。
何时进行 code review?
所有自动化检查 OK 之后(单元测试、格式检查,其他 CI)
合入主分支之前
准备待 review 的代码
准备代码
为了不浪费 reviewer 的时间,让提交的代码容易 review 是提交者的责任。
1 个提交尽量短小精悍。假如 1 个提交涉及的文件超过 5 个,你编写它也用了 1~2 天的时间,预估 review 的时间会超过 20 分钟的话,你可能就需要将其拆分为多个提交。例如,开发人员可以提交一个 commit,用于根据接口和文档为新功能定义 API;以及第二个 commit,为这些接口添加实现。
提交给 reviewer 的代码,必须是完整的、自己 review 过的,并且自测完成之后的代码。
假如是代码重构,不要涉及到功能修改。有几个好处:
代码重构通常涉及到大量文件,在大量的修改中掺杂着的功能修改,很可能会被 reviewer 忽视掉。
代码重构由于涉及的文件改动较大,假如想回退其中涉及的功能修改,会很麻烦。
human review 时间是很宝贵的,应该主要花费在程序逻辑的审查,而不是格式、语法等方面,这些事情可以交给自动化工具去做。
commit message
widely quoted standard
第一行写上一个简短的总结,一般小于 80 个字符(subject)。 假如需要的话,这里可以进行详细说明。总结和详细说明之间添加空行(body)。 使用如下风格:'Fix bug',而不是'Fixed bug'或者'Fixes bug'。这样做主要是和 git 的 merge 或者 revert 产生的 commit message 统一。 空行之后可以有更多的段落。
尝试描述 commit 更改的内容及其执行方式:
> BAD. Don't do this. Make compile again > Good. Add jcsv dependency to fix IntelliJ compilation
找到 reviewer
寻找一个或者两个 reviewer,需要对代码比较熟悉。其中一个是项目 leader 或者高级开发人员。
涉及到多方人员,最好用其他方式沟通,譬如会议等。
执行 code review
code review 是团队不同成员的一个同步点,所以有可能是会阻塞他人工作的。所以 code review 的优先级是需要被提升的(通常以小时为单位)。假如你估计很难有时间来完成这个 review 工作,你需要通知 commiter,以便他能够找其他人去 review 这个提交。
code review 是一门艺术,甚于技术。作为 reviewer,有责任保证代码的质量。
下面是一个 code review 的清单:
目标
这些代码是否达到了作者的目的?每个 change 都需要一个特定的理由(可以是新特性,代码重构,bug 修复等),提交的代码是否真的完成了这个目标?
问问题。函数和类的存在都需要一个理由,当理由不是很充分,这时候也许就说明这个代码需要重写,或者增加注释或者测试用例。
实现
从你的角度,假如你想解决这个问题,会使用什么解决手段?假如和作者的不同,为什么?是你的代码考虑了更多的边界条件?还是更加简洁、简单、清晰、更快、更安全?或者使用了更加先进的设计模式?
是否可以找到更好的抽象方法?
像一个“反对者”一样思考,但是需要以更友好的方式表达。
想一下是否已有相似的代码或者库可以重用?
是否遵循现有的标准模式?已有代码通常围绕命名、程序逻辑分解、数据类型定义等都有标准的模式,通常需要新的提交遵循现有模式。
是否增加了编译或者运行时依赖?保证松耦合。
易读性和风格
想想自己读代码时的感受,是否很快的立即了作者的意图?
代码风格是否保持了统一?
是否有 TODOs?仅仅写个 TODO,会让代码中堆积的 TODO 越来越多,并不会得到及时地处理。 更好的方式是提一个问题单,并在 TODO 后附上问题单号。
提交的代码中不包括被注释的代码。(即不需要的代码就删除)
可维护性
必须有测试用例,并且需要检查其测试用例,是否有覆盖到一些特定场景,是否拉低了覆盖率等。
是否会对现有测试造成破坏?
是否需要集成测试?
检查 code-level document,注释和 commit message 的质量。
外部文档(譬如 README)是否更新?一份陈旧的 README 会比没有 README 更加让人困惑。
如果提交的代码很优秀,简洁、可读性高、效率好、很优雅,请不要吝惜你的赞美之词。
假如提交代码存在较大问题,说明原因之后,用友好的方式驳回提交。
comments 做到三点:简洁、友好、可执行。
不可取的表达:“你的代码有 bug”、“我的代码在你的修改之前是好的”、“这不行”,“结果总是错的”。
表达注意区分仅仅只是给出建议, 或者明确要求修改,又或者是需要讨论或者说明?
完成一次 code review 之后,应该说明作者在修改完你的意见之后,可以自己合入代码,或者需要额外一次的 review。(girrit 可以通过 code review +2)
Code reviews 举例
Inconsistent naming
class MyClass { private int countTotalPageVisits; //R: name variables consistently private int uniqueUsersCount; }
Inconsistent method signatures
interface MyInterface { /** Returns {@link Optional#empty} if s cannot be extracted. */ public Optional<String> extractString(String s); /** Returns null if {@code s} cannot be rewritten. */ //R: should harmonize return values: use Optional<> here, too public String rewriteString(String s); }
Library use
//R: remove and replace by Guava's MapJoiner String joinAndConcatenate(Map<String, String> map, String keyValueSeparator, String keySeparator);
Personal taste
int dayCount; //R: nit: I usually prefer numFoo over fooCount; up to you, but we should keep it consistent in this project
Bugs
//R: This performs numIterations+1 iterations, is that intentional? // If it is, consider changing the numIterations semantics? for (int i = 0; i <= numIterations; ++i) { ... }
Architectural concerns
otherService.call(); //R: I think we should avoid the dependency on OtherService. Can we discuss this in person?
总结
code review 相关:
code review 可以提升代码质量,可以促进团队之间成员的交流。
从 committer 的角度:
code review 可以当成一个学习的手段。
请将提交分成更小的模块,以便你的 reviewer 可以更快的完成。
需要做好充足的准备,才上升到给你 review 代码的人,因为他人的时间是很宝贵的。
从 reviewer 的角度:
code review 可能会阻塞提交者的工作,所以需要将优先级提升。
合库之前你是最后一道关卡,需要对提交的代码质量负责。
不要吝惜赞美之词。
其他
[1] Unlearning toxic behaviors in a code review**ure
—————————————————————
BY:HW-LH





































苏公安网备 32011402010933号