開源日報 每天推薦一個 GitHub 優質開源項目和一篇精選英文科技或編程文章原文，堅持閱讀《開源日報》，保持每日學習的好習慣。
今日推薦開源項目：《群聊軟體 Zulip》
今日推薦英文原文：《How to Improve Your Code Reviews》
今日推薦開源項目：《群聊軟體 Zulip》傳送門：GitHub鏈接
推薦理由：Zulip 是一款功能強大的開源開源群聊軟體，它由 Python 編寫，結合了實時聊天的即時性和線程對話的生產力優勢，被很多大型公司以及其他需要實時聊天系統的用戶使用，也是規模最大，發展最快的開源群聊項目之一。
今日推薦英文原文：《How to Improve Your Code Reviews》作者：Patrick Kalkman
原文鏈接：https://medium.com/better-programming/how-to-improve-your-code-reviews-f5e9d5a6536c
推薦理由：從剛上大學起，老師就一直強調代碼是給其他人看的。對於原作者來說，改動希望儘可能小但又有效；而對與評論者來說，需要做的是幫助改進而不是苛求完美。

How to Improve Your Code Reviews

Feedback can be difficult. Here』s a recipe for your pull requests

Almost twenty years ago, I started as a developer in a company that used code reviews. At that time, I had never done a code review nor was my code ever reviewed.

For my first project, I had to create a COM component in C++ using the ATL framework. ATL uses reference counting to manage the lifetime of an object. Reference counting means that you have to call Release() when you are done using the object. If you forget to call it, it results in a memory leak.

I remember the result of my first code review as if it was yesterday. It was dramatic.

I don』t remember the exact number, but I am sure there were more than 100 review comments. The reviewer mentioned every Release() I forgot. The tone of the review was harsh. I struggled with it.

Was I such a terrible developer?

Currently, I have been doing code reviews for more than a decade. Performing code reviews is the best method to improve the quality of your codebase and create a culture of learning and respect.

Yet there is a specific recipe for successful code reviews.

Why Are Code Reviews Critical?

Open the last book you read about programming or another technical topic and look for a paragraph titled Acknowledgments at the beginning of the book.

I am sure that in this paragraph, the author thanks his editor for helping to create a better version of the book. Editing and reviewing is the standard procedure when writing a book.

Why isn』t this the same for software development?

During a code review, another developer checks your work for errors. The developer will point out improvements, such as:
  • hard-to-understand code
  • unclear names
  • commented code
  • untested code
Besides looking for improvement, the reviewer learns from the solution. You should look at code reviews as an opportunity to grow, and as a safety net — not an opportunity for criticism.

Code reviews are also known to prevent bugs. Research done by IBM² found that each hour of inspection prevented about 100 hours of related work (testing and defect correction).

Automate What Can Be Automated

Before we go on and look at my recipe for successful code reviews, we have to talk about automation.

Don』t waste time during code reviews checking for style errors. Instead, agree on a style guide and use a linter or a static analysis tool to verify that style.

Also, make sure that it』s possible to run a complete build to verify that everything still builds correctly and all the unit tests succeed.

Automating all these tasks will make the contribution from a reviewer more valuable. The reviewer can focus more on other aspects, such as functional errors and readability.

Recipe for Code Reviews

My recipe for successful code review consists of two sets of ingredients, one for the author of the changes and another set for the reviewer.

(Ingredients for a recipe by Jasmin Sessler)

Ingredients for the Author

As the author of the changes, you have the responsibility to make it easy for the reviewer to understand your code review.

The size of the changeset should be small

Nobody likes doing code reviews that consist of thousands of lines of code changes. It will take much time, and there is a high chance that a re-review is necessary due to a large number of changes. Research¹ has shown that the size of the changeset influences the usefulness of comments. As the changeset gets bigger, the number of useful comments drops.

So make sure that the size of your changeset is small, say, less than 250 lines. The review will be of a higher quality.

Proofread your diff

I can』t tell you how many times I found simple mistakes by proofreading my pull requests. Most tools such as GitHub, Bitbucket, or Azure DevOps contain tools to proofread your diff before sending your pull request.

As an author, you should always proofread your code changes to find common mistakes so that the reviewer can focus on other points.

Ingredients for the Reviewer

Aim for improvement, not for perfection

Try to improve the code a notch instead of making it perfect. It helps me to think about it in terms of grades. When I receive a pull request that starts at a D, I help the author to bring it to a C — not perfect but better than it was.

Won』t this degrade the entire codebase to a C? I don』t think so. I find that when I help a developer go from a D to a C, the next pull request they send will start at a C. Within a couple of pull requests, they』re sending me reviews that begin as Bs, which become As by the end of the review.

Respect the scope of the review

Simply, only review the code that was changed. If you see something near the modified code that you feel should be fixed, you can kindly ask the author to fix it. But remember that it is not in the scope of the review.

If the pull request didn』t change a line, it』s out of scope.

The tone of the review

I find the tone of the review one of the most important aspects of a code review. Always try to ask open-ended questions instead of making opinionated statements. Offer other alternatives or possible workarounds. But don』t insist on those alternatives or workarounds.

If you don』t understand something, assume that you, as a reviewer, are missing something and ask for clarification. Try to use the word consider. For example: 「Did you consider refactoring this into a single method?」 or 「Consider renaming this method for readability.」

Review in a timely manner

Try to review the pull request as soon as possible. If you first have to finish your task, let the author know when you will start on the review.

Use a review checklist

You should try to create a checklist that can be used as a reference when performing the code review. Take a look at the following categories for inspiration about items to put on your checklist:
  • Robustness
  • Correctness
  • Design
  • Maintainability
  • REST API design
  • Globalization
  • Performance
  • Security
  • Scalability
  • Testability
Another source for inspiration is ISO 25010, a standard that defines quality characteristics of a software system.

Conclusion

I am sure that code reviews, when done correctly, can improve your codebase and create a culture of learning and respect.

This article describes my definition of a good code review. I listed several ingredients for the author and the reviewer to make sure that you are off to a good start.

For more information, I suggest reading the following articles by other people and organizations on their code review best practices.
  • Code review from Google Engineering
  • How to Make Good Code Reviews Better by Gergely Orosz
  • Code Review Guidelines for Humans by Philipp Hauer
  • Developer』s Guide to a Better Code Review Process from SmartBear
  • How to Do Code Reviews Like a Human By Michael Lynch
  • Humanizing Peer Reviews by Karl E. Wiegers
Thanks for reading!

[1]: Amiangshu Bosu. (May 2015). Characteristics of Useful Code Reviews: An Empirical Study at Microsoft

[2]: Holland, Dick. (December 1999). 「Document Inspection as an Agent of Change,」 Software Quality Professional, Vol. 2, №1, pp. 22–33.

下載開源日報APP：https://openingsource.org/2579/
加入我們：https://openingsource.org/about/join/
關注我們：https://openingsource.org/about/love/