代碼審查-最終指南 (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!

如果您對改善這些準則有任何疑問或反饋，請隨時在下面添加評論！