今日推荐英文原文：《The Do’s and Don’ts of Code Reviews》
推荐理由：开源指北是10月启动的一个项目，是一个开源新手教程，旨在为那些想参与开源的开发者们提供一个丰富详实的操作指南，让更多开发者认识开源、参与开源、爱上开源。目前已经完成了电子书修订活动，在 Gitee 项目页面即可阅读。
今日推荐英文原文：《The Do’s and Don’ts of Code Reviews》作者：Mike Pesate
The Do’s and Don’ts of Code Reviews
Reduce team friction by having healthier code review culturesCode reviews are an essential part of the development process. They help to maintain code integrity, quality, styling, prevent bugs, and even help us learn from others. The big barrier with code reviews is that they are usually done in an impersonal matter — such as leaving comments on a platform like GitHub, Bitbucket, or whatever version control you use on your team.
Since code reviews are done via text — the way we write, the words we choose, the mood we have when reading or writing or anything really can easily create friction with our teammates. To avoid this, we have to be mindful of how we approach code reviews. As such, I’ve compiled a list of Do’s and Don’ts to follow during code reviews.
As a ReviewerHere’s a list of behaviors to do and void when reviewing other people’s code.
- First of all, be polite.
- Be humble, and offer your help.
- If it’s not wrong and the solution is based on preference and opinion, then let it be — unless your team has a specific styling rule on how to solve certain problems.
- Ask for clarification when you have doubts.
- Highlight the good parts of the code as well, not only the mistakes. People deserve to be praised for their work.
- Approach the owner directly if you need clarification on a huge question. Code reviews are mostly async and written. A quick call can help settle doubts quickly.
- Have a checklist of things to look for. This will help speed up and streamline the review process (i.e., check styling, agreements, naming convention, does the code have tests, and more). You can even use tools like a linter to help you cut down on some of the review efforts.
- Write the comments as you want others to write them to you.
- Make time to review the code. Your teammates work depends on you to be complete. Give it the importance it deserves.
- Avoid using words like always or never.
- It might be obvious but, don’t insult people.
- Don’t use hyperbole.
- Avoid jokes and sarcasm. The written word is easily misinterpreted.
- Don’t assume things.
- Avoid blaming people.
- Don’t leave comments like “change this,” “this is wrong,” “find another solution,” etc. Be constructive, offer your help, and give suggestions.
As the AuthorAs the owner of the code, there are certain things you can do to make the review process easier on your team members.
- Be polite.
- Thank people for their help.
- Ask questions on comments you don’t fully understand.
- If someone proposed a solution that you disagree with or don’t understand, try to set a meeting with that person and talk it out.
- Leave clarifications on the sections of code that might be too complex to understand when reading it without having all the context visible. Some solutions span across multiple objects and a code review might not present them in a way that is easy to make the connection.
- Have good and meaningful commit messages.
- Changes you do after opening the code review should have their own commit. This helps reviewers know what changed based on feedback.
- Try to answer as many comments as possible and gives thanks when necessary. Acknowledging someone’s comment doesn’t mean you agree, it just means you read it and appreciate the feedback.
- Try to not take comments personally. They are reviewing your code not you as a person.
- Same as when reviewing, don’t insult people.
- Don’t assume. (See image above)
- If a comment seems like an insult or attack, step back and read it again. You might be misinterpreting it. Write to the commenter directly if you feel like clarification is needed.
- Avoid jokes and sarcasm.
- Don’t shift blame by saying things like “I copied this from this file.” or, “This person made it the same way.” Sometimes, mistakes fall through the cracks, but this shouldn’t be taken as a precedent to keep doing them. Always strive to write better code.
ConclusionThere are more things that you could be doing to improve the way you give and receive reviews, but with this list, you should be on your way to a better approach.
One thing you can do is discuss this post with that colleague that might check all the ticks on the don’ts list. Help them be better by being better yourself. People can’t improve by photosynthesis.