如何有效地執(zhí)行代碼審查

by Sandor Dargo

由Sandor Dargo

使用這些有效的代碼審查指南創(chuàng)建合理的辦公環(huán)境 (Create a sane office environment with these effective code review guidelines)

In my new team, we are working on several guidelines, rules and process improvements. Why do we think these are so important? If things are well-documented, it’s easier for a newcomer to start delivering value. It reduces the possibilities of errors for everyone. It removes lots of possibilities for arguments. And we all know that one cannot win an argument, so we should avoid them at all costs.

在我的新團隊中，我們正在研究一些準則，規(guī)則和流程改進。 為什么我們認為這些是如此重要？ 如果一切都有據(jù)可查，那么新手開始創(chuàng)造價值就更容易了。 它減少了每個人出錯的可能性。 它消除了很多爭論的可能性。 我們都知道， 不能贏得一場辯論 ，因此我們應(yīng)不惜一切代價避免他們。

For a more detail vision about the importance of guidelines, please check out this article. I’ll revisit it soon, by the way.

要詳細了解指南的重要性，請查看本文 。 順便說一下，我會盡快重溫。

This time, I’m going to focus on code reviews and on the corresponding guidelines.

這次，我將專注于代碼審查和相應(yīng)的準則。

代碼審查的目的 (The aim of the code review)

Reviewing a pull request is an important and sensitive task. In my opinion, it is at least as important as writing the code. Besides, reviewing someone else’s code is a not just a technical task, it’s also a human one. That gives most of its delicateness.

審核拉取請求是一項重要而敏感的任務(wù)。 在我看來，它至少與編寫代碼一樣重要。 此外，審查他人的代碼不僅是一項技術(shù)任務(wù)，而且是一項人工任務(wù)。 這充分體現(xiàn)了其精致性。

So let me start with the most important rule that you should always have in mind whenever you start to review a pull request or whenever you open up a review you received:

因此，讓我從最重要的規(guī)則開始，無論何時開始審閱拉取請求或何時打開收到的評論，都應(yīng)始終牢記：

No comment should be personal. No comment should be made about the author or the reviewer. A review must always be about the code!

沒有評論應(yīng)該是個人的。 不要對作者或?qū)徃迦税l(fā)表評論。 審查必須始終與代碼有關(guān)！

The aim of a code review is to make the code better, to detect bugs before merging and delivering, and to improve maintainability of a given code base.

代碼審查的目的是使代碼更好，在合并和交付之前檢測錯誤，并提高給定代碼庫的可維護性。

代碼審核中要檢查的項目 (Items to be checked in a code review)

Reviewing code is difficult , and it’s a very broad task. According to my bosses, I’m considered a good code reviewer. But still, I think my effectiveness could be improved a lot. I think that following checklists, in most cases, can be a huge help.

審查代碼很困難，這是一項非常廣泛的任務(wù)。 根據(jù)老板的說法，我被認為是一名優(yōu)秀的代碼審閱者。 但是，我仍然認為我的效率可以大大提高。 我認為，在大多數(shù)情況下，遵循清單可以提供巨大幫助。

Now, obviously, some of those checklists and/or tasks will be language-specific. However, reviews are helped by the same concepts existing in multiple code languages.

現(xiàn)在，顯然，其中一些清單和/或任務(wù)將是特定于語言的。 但是，通過多種代碼語言中存在的相同概念可以幫助進行審閱。

These lists are mostly here to give you some ideas, as they are far from complete. Feel free to use them, update them, personalize them, or just let them inspire you to come up with completely new ones.

這些清單大多是在這里為您提供一些想法，因為它們還遠遠不夠完整。 隨意使用它們，對其進行更新，對其進行個性化設(shè)置，或者只是讓它們激發(fā)您提出全新的想法。

I think that one reviewer shouldn’t use them all, but maybe just a few. But if you have separate checklists, it’s easy to share the tasks.

我認為，一位審稿人不應(yīng)該全部使用它們，而應(yīng)該只使用其中一些。 但是，如果您有單獨的清單，則共享任務(wù)很容易。

Not all the checklists are there to be used for all code reviews. If the pull request is a really small bugfix, just correcting an off-by-one in a condition, it will not require checking the design of the whole domain.

并非所有清單都可用于所有代碼審查。 如果拉取請求是一個很小的錯誤修正，只需在某種情況下更正單個錯誤，就不需要檢查整個域的設(shè)計。

清單類型 (Types of checklists)

全過程清單 (Full process checklist)

This one focuses on some foundational characteristics of a pull request. Make sure that the new commits don’t break the compilation or the tests. Your Continuous Integration pipeline should take care of this, but in case not — don’t forget about it. Otherwise, check these:

這一節(jié)重點介紹拉取請求的一些基本特征。 確保新提交不會破壞編譯或測試。 您的持續(xù)集成管道應(yīng)解決此問題，但如果不這樣做，請不要忘記。 否則，請檢查以下內(nèi)容：

• Are new unit/regression tests added?
  是否添加了新的單元/回歸測試？
• Are there new compiler warnings?
  是否有新的編譯器警告？
• Does the change functionally make sense?
  更改在功能上有意義嗎？
• Are there a lot of dependencies?
  有很多依賴性嗎？
• Are the commit messages clean?
  提交消息是否干凈？

SOLID(面向?qū)ο笤O(shè)計)原理清單 (SOLID (object-oriented design) principles checklist)

In order to verify the sanity of the design, it’s worth going through the SOLID principles. It’s useful to expand these items into sublists, which helps to verify each principle:

為了驗證設(shè)計的合理性，值得遵循SOLID原則。 將這些項目擴展到子列表中很有用，這有助于驗證每個原理：

• Single responsibility principles
  單一責(zé)任原則
• Open/closed principle
  開閉原則
• Liskov substitution principle
  里斯科夫替代原則
• Interface segregation principle
  接口隔離原理
• Dependency inversion principle
  依賴倒置原則

安全清單 (Security checklist)

Your application might or might not be security-critical. As soon as it’s hacked once or it fails because of some messy input, it will become one. This checklist should be heavily language dependent (I’m giving you one for C++). The list is extracted mainly from this talk on secure programming practices at the NDC Security Conference at 2018

您的應(yīng)用程序可能會或可能不會對安全性至關(guān)重要。 一旦它被黑客入侵了一次，或者由于一些混亂的輸入而失敗了，它將變成一個。 此清單應(yīng)在很大程度上取決于語言(我為您提供了C ++)。 該列表主要摘自2018年NDC安全會議上有關(guān)安全編程實踐的演講

• Is external input handled properly?
  是否正確處理了外部輸入？
• Are C-style interfaces used?
  是否使用C風(fēng)格的接口？

• Is the new operator superfluously used instead of stack allocation?

  是否多余地使用了new運算符而不是堆棧分配？

• Are there lots of (error-prone) size calculations?
  有很多(容易出錯的)大小計算嗎？
• Are pointers used a lot?
  指針經(jīng)常使用嗎？
• Are shared_ptrs used a lot?
  經(jīng)常使用shared_ptrs嗎？
• Are there any threads?
  有線程嗎？

測試最佳做法清單 (Testing best practices checklist)

I hope we all agree that testing is part of a developer’s job. If we had a discussion on testing, it would be about the different ways of doing it, not whether we should do it or not.

我希望我們都同意測試是開發(fā)人員工作的一部分。 如果我們討論測試，那就是測試的不同方式，而不是我們是否應(yīng)該進行測試。

The bad news is that there is no one way fits for all. Still, I’d advise you to follow the cycle of Test Driven Development. The good news is that, on a project, there is at least a common understanding about what should be done.

壞消息是，沒有一種方法適合所有人。 不過，我還是建議您遵循“測試驅(qū)動開發(fā)”的周期。 好消息是，在一個項目上，至少應(yīng)該達成共識。

If there is none, step in and advocate for testing, gather articles and studies, and convince the team. You’ll be much more respected.

如果沒有，請介入并主張進行測試，收集文章和研究，并說服團隊。 您將受到更多的尊重。

Here a few points to clarify in regards to the testing part:

以下是有關(guān)測試部分的一些要點：

• Are there enough unit tests?
  有足夠的單元測試嗎？
• Are there enough non-regression tests?
  有足夠的非回歸測試嗎？
• Do tests test one thing?
  測試測試一件事嗎？
• Do they have assertions? (A test might have multiple assertions, still logically they assert one thing)
  他們有主張嗎？ (一個測試可能有多個斷言，但從邏輯上講，它們斷言了一件事)
• Are they readable?
  它們可讀嗎？
• How are dates used? (Fixed vs. generated)
  如何使用日期？ (固定與生成)

代碼可讀性清單 (Code readability checklist)

We — developers — are all authors. If we do an impeccable job, our code will read like a prose. I’m not saying that you should always reach this goal for the whole codebase, but you should aim for that.

我們(開發(fā)人員)都是作者。 如果我們做的無懈可擊， 我們的代碼將像散文一樣讀起來 。 我并不是說您應(yīng)該始終在整個代碼庫中都達到這個目標，但是您應(yīng)該為此而努力。

The code reviewer has a huge responsibility here. If you are reading a pull request, please think about the following questions:

代碼審查員在這里負有巨大責(zé)任。 如果您正在閱讀請求請求，請考慮以下問題：

• Are names meaningful?
  名稱有意義嗎？
• Are classes/functions small enough?
  類/函數(shù)足夠小嗎？
• Does the code “read like a prose”?
  該代碼是否“讀起來像散文”？
• Is the code well-formatted?
  代碼格式正確嗎？
• Is there duplicated code?
  有重復(fù)的代碼嗎？

資源處理清單，又稱RAII (Resource handling checklist, a.k.a. RAII)

This last one is rather language-specific. It’s not only for C++, but mostly. If you are a C++ developer and you’ve ever fought against dangling pointers, memory leaks, and nasty core dumps, then you know what I mean.

最后一個是特定于語言的。 它不僅適用于C ++，而且適用于大多數(shù)情況。 如果您是C ++開發(fā)人員，并且曾經(jīng)與懸空指針，內(nèi)存泄漏和討厭的內(nèi)核轉(zhuǎn)儲進行過斗爭，那么您就知道我的意思了。

It can be really difficult for a non-expert to spot these issues. But following a helpful checklist can help you both in pointing out the problematic lines and in developing the RAII expertise.

非專家真的很難發(fā)現(xiàn)這些問題。 但是遵循一份有用的清單可以幫助您指出有問題的路線以及發(fā)展RAII的專業(yè)知識。

• Is object ownership clarified?
  對象所有權(quán)是否明確？
• Are objects properly destroyed/ is the memory correctly deallocated?
  對象是否已正確銷毀/內(nèi)存是否已正確釋放？
• Are new fields properly handled?
  是否正確處理了新字段？
• Are Fields correctly initialized in the constructors?
  字段是否在構(gòu)造函數(shù)中正確初始化？
• Are comparison operators updated?
  比較運算符是否已更新？

準則審查者的行為準則 (The code of conduct for code reviewers)

As stated before, commenting on someone else’s code is also a human task, so be nice to your fellow developers. Here are some pieces of advice. Following them will markedly decrease the chance that developers will cry or throw chairs at each other in the office. (But I have never seen the latter — so far…)

如前所述，注釋其他人的代碼也是一項艱巨的任務(wù)，因此對其他開發(fā)人員要好。 這里有一些建議。 跟隨他們將顯著減少開發(fā)人員在辦公室互相哭泣或丟椅子的機會。 (但到目前為止，我還沒有見過后者-)

不要 (Don’ts)

• Don’t refer to personal traits and don’t judge (for instance, refrain from saying you/your code is stupid…)
  不要提及個人特質(zhì)，不要做出判斷(例如，不要說您/您的代碼很愚蠢……)
• Don’t make demands (at least put a please in there and explain why you’re asking for a change)
  不要提出要求(至少在里面請一個，并解釋為什么您要更改)
• Don’t be sarcastic, even if you are buddies. Other reviewers/readers might find some comments inappropriate
  即使您是哥們，也不要諷刺。 其他評論者/讀者可能會發(fā)現(xiàn)一些不適當?shù)脑u論
• Never say never, nor always. There will always be exceptions. So treat this rule with care…
  永遠不要說永遠也永遠不要。 總是會有例外。 因此，請謹慎對待此規(guī)則...
• Avoid selective ownership of the code (that is, don’t use “mine,” “not mine,” “yours”…)
  避免對代碼進行有選擇的所有權(quán)(即，不要使用“我的”，“不是我的”，“您的……”)

多斯 (Dos)

• Ask questions.
  問問題。
• Ask for clarification.
  要求澄清。
• Be explicit. Remember people don’t always understand your intentions online.
  要明確。 請記住，人們并不總是在線上了解您的意圖。
• Seek to understand the author’s perspective.
  試圖了解作者的觀點。
• If discussions turn too philosophical or academic, move the discussion offline
  如果討論太過哲學(xué)或?qū)W術(shù)性問題，請離線進行討論
• Identify ways to simplify the code while still solving the problem.
  確定在解決問題的同時簡化代碼的方法。
• Communicate which ideas you feel strongly about and which you don’t. If you just express your preference, say that it’s only your preference.
  傳達您對哪些想法有強烈的想法，而哪些則不是。 如果您只是表達自己的偏好，請說這只是您的偏好。
• Educate. If you suggest something, share proofs for why it’s better (like articles, studies, books, and so on).
  教育。 如果您提出建議，請分享證明它為何更好的證據(jù)(例如文章，研究，書籍等)。

作者規(guī)則 (Rules for the authors)

• Be humble and honest about the submitted code. Mistakes happen every day, and the process is there to support you.
  對提交的代碼保持謙虛和誠實。 每天都會發(fā)生錯誤，并且流程會一直為您提供支持。
• Remember that you shouldn’t take it personally. The review is of the code, not of you.
  請記住，您不應(yīng)該個人化。 審閱的是代碼，而不是您的。
• Explain why the code exists.
  說明代碼為何存在。
• Follow guidelines.
  遵循準則。
• Seek to understand the reviewer’s perspective.
  試圖了解審稿人的觀點。
• Be grateful for alternative suggestions and keep the discussion technical. Try to learn from different perspectives.
  感謝其他建議，并保持討論的技術(shù)性。 嘗試從不同角度學(xué)習(xí)。

呼吁采取行動 (Call to action)

• Make thorough code reviews. You will learn a lot, just like your fellow developers.
  進行徹底的代碼審查。 您將像其他開發(fā)人員一樣學(xué)到很多東西。
• Emphasize the importance of proper code reviews in your teams, and if necessary, educate your colleagues how to review code.
  強調(diào)在團隊中進行正確的代碼審查的重要性，并在必要時教育同事如何審查代碼。

• Check out and star this repository where I’ve collected some checklists and ideas. Feel free to contribute, and add what you have found important!

  簽出并在該資料庫中加注星標，以收集我的一些清單和想法。 隨時做出貢獻，并添加您發(fā)現(xiàn)的重要內(nèi)容！

This article has been originally published on my blog.

本文最初發(fā)布在我的博客上 。

翻譯自: https://www.freecodecamp.org/news/create-a-sane-office-environment-with-these-effective-code-review-guidelines-1d99ae2bdd47/

如何有效地執(zhí)行代碼審查

總結(jié)

以上是生活随笔為你收集整理的如何有效地执行代码审查_使用这些有效的代码审查指南创建合理的办公环境的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。