代码审查-最终指南 (Code Review — The Ultimate Guide)

构建团队代码审查流程的终极指南 (The ultimate guide for building your team’s code review process)

After conducting hundreds of code reviews, leading R&D teams and pushing several unintentional bugs myself, I’ve decided to share my conclusions for building the ultimate code review process for your team.

在进行了数百次代码审查，领导研发团队并亲自解决了一些无意的错误之后，我决定分享我的结论，以为您的团队构建最终的代码审查流程。

This article assumes you know what a code review is. So if you don’t, click here for a great intro.

本文假设您知道什么是代码审查。因此，如果您不这样做，请单击此处获取出色的介绍。

Let’s quickly state some straightforward reasons as to why you should do code reviews:

让我们快速说明为什么要进行代码审查的一些直接原因：

Can help reduce bugs in code.
可以帮助减少代码中的错误。
Validate that all coding requirements have been filled.
验证是否已满足所有编码要求。
An effective way to learn from peers and get familiar with the code base.
向同龄人学习并熟悉代码库的有效方法。
Helps maintain code styling across the team.
帮助维护整个团队的代码样式。
Team cohesion — encourage developers to talk to each other on best practices and coding standards.
团队凝聚力-鼓励开发人员就最佳实践和编码标准相互交流。
Improves overall code quality due to peer pressure.
由于同伴的压力，提高了整体代码质量。

However, code reviews can be one of the most difficult and time-consuming parts of the software development process.

但是，代码审查可能是软件开发过程中最困难，最耗时的部分之一。

We’ve all been there. You might have waited days until your code was reviewed. Once it was reviewed you started a ping pong with the reviewer of resubmitting your pull request. All the sudden you’re spending weeks going back and forth. You are context switching between new features and old commits that still need polishing.

我们都去过那里。您可能已经等了几天，直到代码被审查。一经审核，您就可以与审核员开始乒乓球，重新提交您的拉取请求。突然之间，您要花费数周的时间来回移动。您正在新功能和仍需要完善的旧提交之间进行上下文切换。

If the code review process is not planned right, it could have more cost than value.

如果没有正确计划代码审查流程，那么成本可能会超过价值。

This is why it’s extremely important to structure and build a well-defined process for code reviews within your engineering team.

这就是为什么在您的工程团队中构造和建立定义良好的代码审查流程极为重要的原因。

In general, you’ll need to have in place well-defined guidelines for both the reviewer and reviewee, prior to creating a pull request and while it’s being reviewed. More specifically:

通常，在创建拉取请求之前和正在审阅期间，您都需要为审阅者和受审者都制定明确的准则。进一步来说：

定义用于创建拉取请求的条件。 (Define perquisites for creating pull requests.)

I’ve found that the following greatly reduces friction:

我发现以下可以大大减少摩擦：

Make sure code compiles successfully.
确保代码成功编译。
Read and annotate your code.
阅读并注释您的代码。
Build and run tests that validate the scope of your code.
建立并运行测试以验证代码范围。
All code in codebase should be tested.
代码库中的所有代码都应经过测试。
Link relevant tickets/items in your task management tool (JIRA for example) to your pull request.
将任务管理工具(例如JIRA)中的相关票证/项目链接到您的请求请求。
Do not assign a reviewer until you’ve finalized the above.
在完成上述工作之前，请勿分配审阅者。

定义受审者职责 (Define reviewee responsibilities)

While the reviewer is last in the chain of merging your PR, the better it’s handed over by the reviewee, the fewer risks you’ll run into in the long term. Here are some guidelines that can greatly help:

虽然审阅者在合并您的PR链中处于最后一位，但审阅者交出的越好，从长远来看，您遇到的风险就越少。以下是一些可以大大帮助您的准则：

Communicate with your reviewer — Give your reviewers background about your task. Since most of us pull request authors have likely been reviewers already, simply put yourself in the shoes of the reviewer and ask, “How could this be easier for me?”
与您的审阅者交流 —为您的审阅者提供有关您任务的背景。由于我们大多数人的拉动请求作者可能已经是审稿人，所以只需将自己放在审稿人的面前，然后问：“这对我来说会更容易吗？”
Make smaller pull requests — Making smaller pull requests is the best way to speed up your review time. Keep your pull requests small so that you can iterate more quickly and accurately. In general, smaller code changes are also easier to test and verify as stable. When a pull request is small, it’s easier for the reviewers to understand the context and reason with the logic.
提出较小的提取请求 - 提出较小的提取请求是缩短审核时间的最佳方法。保持拉取请求较小，以便可以更快，更准确地进行迭代。通常，较小的代码更改也更易于测试和验证是否稳定。当拉取请求较小时，审阅者更容易理解逻辑的上下文和原因。
Avoid changes during the code review — Major changes in the middle of code review basically resets the entire review process. If you need to make major changes after submitting a review, you may want to ship your existing review and follow-up with additional changes. If you need to make major changes after starting the code review process, make sure to communicate this to the reviewer as early in the process as possible.
避免在代码检查期间进行更改 - 代码检查过程中的主要更改基本上会重置整个检查过程。如果您在提交评论后需要进行重大更改，则可能需要发送现有的评论并进行其他更改。如果您需要在开始代码审查过程之后进行重大更改，请确保在过程中尽早将此信息告知审查者。
Respond to all actionable code review feedback — Even if you don’t implement their feedback, respond to it and explain your reasoning. If there’s something you don’t understand, ask questions inside or outside the code review.
响应所有可操作的代码审阅反馈 -即使您不执行他们的反馈，也要对其进行答复并解释您的推理。如果您不了解某些内容，请在代码审查的内部或外部提出问题。
Code reviews are discussions, not dictation — You can think of most code review feedback as a suggestion more than an order. It’s fine to disagree with a reviewer’s feedback but you need to explain why and give them an opportunity to respond.
代码审查是讨论，而不是听写 -您可以将大多数代码审查反馈视为建议，而不是命令。可以不同意审阅者的反馈，但您需要解释原因并给予他们回应的机会。

定义审阅者职责 (Define reviewer responsibilities)

Since the reviewer is last in the chain before merging the code, a great part of the responsibility is on him for reducing errors. The reviewer should:

由于审阅者在合并代码之前是链中的最后一员，因此减少错误的责任很大。审稿人应：

Be aware to the task description and requirements.
注意任务说明和要求。
Make sure to completely understand the code.
确保完全理解代码。
Evaluate all the architecture tradeoffs.
评估所有架构权衡。
Divide your comments into 3 categories: Critical, Optional and Positive. The first are comments that the developer must accept to change, and the latter being comments that let the developer know your appreciation for nice pieces of code.
将您的评论分为3类：关键，可选和肯定。第一个是开发人员必须接受才能更改的注释，第二个是使开发人员知道您对精美代码的赞赏的注释。

Also, avoid many comments and use Github review instead (see example below).

另外，请避免使用大量评论，而应使用Github评论(请参见下面的示例)。

When you have several comments, you should use the review option in Github, instead of comment each of them separately, and notify the developer (PR owner) when you’re done.

当您有多条评论时，应使用Github中的review选项，而不是分别评论每条评论，并在完成后通知开发人员(公关所有者)。

Finally, I’ve found that asking the following questions is a great tool for an overall better and easier reviewing process:

最后，我发现提出以下问题对于整体上更好，更轻松地进行审核是一个很好的工具：

Am I having difficulty in understanding this code?
我在理解此代码时有困难吗？
Is there any complexity in the code which could be reduced by refactoring?
代码中是否存在可以通过重构减少的复杂性？
Is the code well organized in a package structure which makes sense?
代码是否合理地以有意义的包结构进行了组织？
Are the class names intuitive and is it obvious what they do?
类名是直观的，并且它们的作用很明显吗？
Are there any classes which are notably large?
有没有特别大的课程？
Are there any particularly long methods?
有没有特别长的方法？
Do all the method names seem clear and intuitive?
所有方法名称看起来清晰直观吗？
Is the code well documented?
该代码是否有据可查？
Is the code well tested?
代码是否经过良好测试？
Are there ways in which this code could be made more efficient?
有什么方法可以使此代码更有效？
Does the code meet our teams styling standards?
该代码是否符合我们团队的样式标准？

There are various effective and different code review practices that vary based on team’s needs. So assume this is my personal opinion and that there are other ways that might work for your team. In the end, building such a sensitive process should be subjective to your companies goals, team’s culture and overall R&D structure.

有多种有效且不同的代码检查实践，具体取决于团队的需求。因此，假设这是我的个人观点，并且还有其他一些方法可以为您的团队工作。最后，建立这样一个敏感的流程应该取决于您公司的目标，团队的文化和整体研发结构。

If you have any questions or feedback for improving these guidelines, please feel free to add a comment below!

如果您对改善这些准则有任何疑问或反馈，请随时在下面添加评论！