如何充分利用代码审查

Code reviews are important to our work as software engineers. Just like writing code, it’s critical that we practice reviewing code and giving feedback on it. Below are a few thoughts from engineers at VTS on objectives of a code review and how we can get better at them.

代码审查对于我们作为软件工程师的工作很重要。 就像编写代码一样，我们必须练习审查代码并提供反馈，这一点至关重要。 以下是VTS工程师对代码审查目标的一些想法，以及我们如何才能更好地实现它们。

Code reviews are about empowering each other to write really great code.

代码审查是关于互相授权以编写真正的代码。

— Amy Gebhart

— 艾米·盖伯特 ( Amy Gebhart)

目标 (Objectives)

The two main objectives of a code review are to:

代码审查的两个主要目标是：

提高代码质量 (Improve code quality)

Reviews can improve code quality by:

评论可以通过以下方式提高代码质量：

• Finding and fixing code smells. We want quality code, especially if the app is not a prototype.
  查找并修复代码异味。 我们需要高质量的代码，尤其是在应用不是原型的情况下。
• Validating that proper short-term/long-term balance considerations are exercised.
  验证是否已行使适当的短期/长期余额考虑因素。
• Catching bugs and edge cases. Not all bugs nor edge cases will be caught, but a review can reduce them. Any that slip through are a good learning opportunity.
  捕获错误和边缘案例。 并非所有的bug或边缘情况都将被捕获，但是通过审查可以减少它们。 碰到的任何东西都是很好的学习机会。
• Ensuring good commit practices are followed.
  确保遵循良好的提交惯例。

共享技术和领域知识。 (Share technical and domain knowledge.)

There should be teaching and learning for both the author and reviewer.

作者和审稿人都应该有教与学。

提供有用评论的提示 (Tips for Giving a Useful Review)

The practices below can help you achieve the above objectives when doing a code review.

下面的实践可以帮助您在进行代码审查时实现以上目标。

询问您对本代码审查的看法 (Ask what angle you bring to this code review)

Take time to reflect on why your (or your team’s) review was requested for this pull request. You are likely being asked because of either your domain knowledge or your technical knowledge. Knowing this can adjust how you approach the code review. You may need to review the entire request, or you may only have a few lines that are pertinent.

花一些时间来思考为什么要为此请求请求您(或您的团队)的审查。 您可能因为您的领域知识或技术知识而被问到。 知道这一点可以调整您进行代码审查的方式。 您可能需要查看整个请求，或者可能只有几行相关。

Once you know your angle then it’s easier to know how you can contribute to the code. Can you improve the design of a new class? Can you help refactor some of the code? Are there edge cases you know from experience that are not addressed?

一旦知道了角度，就更容易知道如何为代码做出贡献。 您可以改善新班级的设计吗？ 您可以帮助重构某些代码吗？ 您是否有从经验中得知的未解决的极端案例？

If the code addresses a problem, you can use your angle to think of how you would have solved the problem. Does your solution differ? You solution could differ because you:

如果代码解决了问题，则可以从角度考虑如何解决问题。 您的解决方案是否不同？ 您的解决方案可能会有所不同，因为您：

• Have a different skill and/or experience level
  具有不同的技能和/或经验水平
• Lack context on the problem being solved
  缺乏解决问题的背景
• Bring a different domain knowledge to the problem (e.g. data quality vs. performance)
  为问题带来不同的领域知识(例如，数据质量与性能)
• Have a different level of exposure and experience with the code base
  对代码库有不同程度的了解和经验

Different solutions does not necessarily imply one is better than another — it’s just a different way to approach the problem. If you feel a different solution is better, be sure to explain why. These differences can lead to questions about the author’s implementation and can start a constructive conversation.

不同的解决方案并不一定意味着一个解决方案要比另一个解决方案好–这只是解决问题的另一种方法。 如果您觉得其他解决方案更好，请务必说明原因。 这些差异可能导致对作者的实现方式提出疑问，并可能引发建设性对话。

The outcome of this practice is that you offer perspectives the author didn’t have or maybe didn’t think about.

这种做法的结果 是，您可以提供作者没有或可能没有考虑过的观点。

不批准您不了解的内容 (Do not approve what you do not understand)

This applies to all levels of engineers. If you need more information from the author, then ask. If an author wants a pull request approved, then they will take the time to explain the code to you.

这适用于所有级别的工程师。 如果您需要作者的更多信息，请询问。 如果作者希望批准请求请求，那么他们将花时间向您解释代码。

You should not feel pressured into approving a pull request. You should also not feel foolish for asking questions to clarify what you do not understand. It’s important for every workplace to foster psychological safety so that everyone can feel free to share ideas and ask questions.

您不应感到压力批准批准请求。 您也不应该因提出问题来澄清您不了解的内容而感到愚蠢。 对于每个工作场所而言， 培养心理安全感至关重要，这样每个人都可以自由地分享想法和提出问题。

There is also the chance that if you do not understand it then the author doesn’t understand it either. Maybe it was a copy/paste from Stack Overflow. Maybe they stepped away from the code and can’t remember what they were trying to do. Maybe it’s just too complicated. Ensure understanding before merging.

还有一种可能是，如果您不理解它，那么作者也将不理解它。 也许是从Stack Overflow复制/粘贴。 也许他们放弃了代码，不记得他们想做什么。 也许太复杂了。 合并前请确保理解。

The outcome of this practice is possibly a simpler solution that’s easier to maintain and reason about.

这种做法的结果 可能是更简单的解决方案，更易于维护和推论。

您可能需要在本地结帐请求 (You may need to checkout the request locally)

Sometimes you need to see how the code is being used in the system as a whole. If this is the case, you likely need to check out the request locally and look through the files in your editor. Ask questions like:

有时您需要查看代码在整个系统中的使用情况。 在这种情况下，您可能需要在本地签出请求并在编辑器中浏览文件。 提出类似的问题：

• Is this method being used properly?
  该方法是否正确使用？
• Does this adhere to the same design as other classes like it?
  这是否遵循与其他类相同的设计？
• Are there even more opportunities to refactor and do they belong with this pull request?
  还有更多重构的机会，它们是否属于此请求请求？
• Are the tests comprehensive enough?
  测试足够全面吗？
• How does this integrate with the rest of the system?
  这如何与系统的其余部分集成？

The outcome of this practice is that you better understand how the code fits with the software as a whole. This can lead you to find further opportunities to refactor or fix code that aligns well with the pull request.

这种做法的结果是，您可以更好地了解代码如何与软件整体相适应。 这可能会导致您找到其他机会来重构或修复与拉取请求完全吻合的代码。

避免无建议的批评 (Avoid criticism without a suggestion)

If there truly is a flaw in a pull request, then it’s important to point it out. What is equally important is to follow that up with a suggestion on how to fix or avoid that flaw. It’s important to do so respectfully and in a non-degrading way. You can do so by fully explaining why something may not work and what a better solution is. You can also link articles or Stack Overflow answers.

如果拉取请求确实存在缺陷，那么指出这一点很重要。 同样重要的是，在此之后提出有关如何修复或避免该缺陷的建议。 重要的是要做到尊重和以不降级的方式。 您可以通过充分解释为什么某些东西可能无法工作以及什么是更好的解决方案来做到这一点。 您还可以链接文章或堆栈溢出答案。

Admittedly, there may be times where you know there is a code smell or a way to improve, but are unsure what to do. If that is the case, be sure to leave an open ended question for the author so you can start a conversation on how to fix it.

诚然，有时您可能知道有某种代码味道或一种改进方法，但不确定该怎么做。 如果是这种情况，请务必为作者留下一个开放式问题，以便您可以就如何解决此问题展开对话。

The outcome of this practice is that the author understands why the criticism was given and what a solution could be.

这种做法的结果 是，作者了解为什么会提出批评以及可以采取什么解决方案。

寻找庆祝机会 (Find opportunities for celebration)

We all need positive feedback to shore up our confidence. Putting your code out there for others to critically analyze is a daunting task. We need to find ways to keep encouraging each other to do our best. Do you know if the author is trying to master a refactoring technique? Point out the progress they are making if you see that technique. Is code now more readable? Praise them for it. This applies to all levels of engineers.

我们都需要积极的反馈，以增强我们的信心。 将您的代码放到那里以供他人进行严格分析是一项艰巨的任务。 我们需要找到方法，以不断鼓励彼此尽力而为。 您是否知道作者是否试图掌握一种重构技术？ 如果您看到该技术，请指出他们正在取得的进展。 代码现在更具可读性了吗？ 为此赞美他们。 这适用于所有级别的工程师。

Another benefit is that it shows you took the review seriously. Sometimes we do not have any feedback and simply approve the request. How does the author know you really looked at it? Celebrating something in the code is one way.

另一个好处是，它表明您认真对待了此次审核。 有时我们没有任何反馈，只是批准请求。 作者怎么知道您真的看过它？ 庆祝代码中的某些内容是一种方法。

The outcome of this practice is the author feels encouraged to continue contributing to the code and to keep learning and get better at their craft.

这种做法的结果 是使作者感到鼓舞，他们继续为代码做贡献，并继续学习并精通他们的技巧。

保持反馈回路紧密 (Keep the feedback loop tight)

Feedback is important through the whole process of writing code. When appropriate, seek for feedback before you put up your pull request. In the beginning stages, it doesn’t generally have to be about the code. You can ask if there is an idea you haven’t considered or if this is the best path forward. Talk with your teammates or those with domain/context knowledge early on.

在编写代码的整个过程中，反馈很重要。 在适当的时候，在提出拉取请求之前寻求反馈。 在开始阶段，通常不必与代码有关。 您可以询问是否有未考虑过的想法，或者这是前进的最佳途径。 尽早与您的队友或具有领域/背景知识的人交谈。

Once the request is up, be sure to respond quickly to any feedback. It’s important to keep working on the pull request so it is not abandoned. It will also help you to not context-switch too often.

提出要求后，请务必快速回应任何反馈。 继续处理请求请求很重要，这样它就不会被放弃。 它还将帮助您不要过于频繁地进行上下文切换。

You should also balance asynchronous and synchronous conversations. Sometimes it’s just faster to talk in person and ensure understanding among all parties. If a decision is reached there, be sure to record it in writing.

您还应该平衡异步和同步对话。 有时，亲自交谈并确保各方之间的理解会更快。 如果在那里做出决定，请务必以书面形式记录下来。

The outcome of this practice is merging your pull requests quicker. If you’re working on a big code base with lots of merges, this is particularly important.

这种做法的结果 是更快地合并了您的请求请求。 如果您正在处理具有大量合并的大型代码库，则这一点尤其重要。

关于提交的注释 (A note about commits)

This short section deserves its own post, but it’s very important to mention here as part of code review practices. To help the reviewer, the author needs to maintain a clean and informative commit history. Good commits can help you get the most useful feedback possible

这一小节值得一提，但在这里作为代码审查实践的一部分进行提及非常重要。 为了帮助审稿人，作者需要保持干净且内容丰富的提交历史。 良好的提交可以帮助您获得最有用的反馈

A good commit history means the commits are broken up vertically instead of horizontally. This means that each commit passes all tests and doesn’t break the main branch. A good commit history also means the commits tell one cohesive story as part of the pull request. The person reviewing your code can follow your thinking and decision-making. A good commit history also leaves detailed notes on why you did what you did. Simply stating that you did something does not expand on anything the code does not already do. A good commit history can act as documentation for your application. Lastly, good commits should be self-contained, meaning they add value on their own and do not require a reviewer to look at other commits to understand them.

良好的提交历史意味着这些提交在垂直方向而不是水平方向上被分解。 这意味着每次提交都会通过所有测试，并且不会破坏主分支。 良好的提交历史也意味着提交作为下拉请求的一部分讲述一个内聚的故事。 审查您的代码的人可以遵循您的想法和决策。 良好的提交历史还留下了详细说明您为什么要做的事情。 简单地说，您做了什么并不会扩展代码尚未完成的任何事情。 良好的提交历史可以作为您的应用程序的文档。 最后，好的提交应该是独立的，这意味着它们可以自己增加价值，并且不需要审阅者去查看其他提交以了解它们。

As a reviewer, be sure to keep on the lookout for opportunities to create good commits.

作为审阅者，请务必注意寻找机会来做出好的承诺。

The outcome of this practice is a code base with informative commits that document how your application works for generations of developers to come. Another positive outcome is it makes for an easier code review.

这种实践的结果 是一个具有丰富信息提交的代码库，该文件记录了您的应用程序如何为下一代开发人员服务。 另一个积极的结果是，它使代码审查更加容易。

Contributors:

贡献者：

• Jacobo Blasco
  雅各布·布拉斯科
• Caley Brock
  凯莉·布洛克(Caley Brock)
• Andrew Marshall
  安德鲁·马歇尔
• Clemens Park
  克莱门斯公园
• Jess Kane
  杰斯·凯恩(Jess Kane)
• Eric Firth
  埃里克·费思(Eric Firth)

翻译自: https://buildingvts.com/how-to-make-the-most-out-of-code-reviews-53ba14a11948