今日推荐英文原文：《How to Improve Your Code Reviews》
推荐理由：Zulip 是一款功能强大的开源开源群聊软件，它由 Python 编写，结合了实时聊天的即时性和线程对话的生产力优势，被很多大型公司以及其他需要实时聊天系统的用户使用，也是规模最大，发展最快的开源群聊项目之一。
今日推荐英文原文：《How to Improve Your Code Reviews》作者：Patrick Kalkman
How to Improve Your Code Reviews
Feedback can be difficult. Here’s a recipe for your pull requestsAlmost 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
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 AutomatedBefore 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 ReviewsMy 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 AuthorAs 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 smallNobody 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 diffI 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 perfectionTry 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 reviewSimply, 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 reviewI 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 mannerTry 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 checklistYou 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:
- REST API design
ConclusionI 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
: Amiangshu Bosu. (May 2015). Characteristics of Useful Code Reviews: An Empirical Study at Microsoft
: Holland, Dick. (December 1999). “Document Inspection as an Agent of Change,” Software Quality Professional, Vol. 2, №1, pp. 22–33.