開源日報 每天推薦一個 GitHub 優質開源項目和一篇精選英文科技或編程文章原文,堅持閱讀《開源日報》,保持每日學習的好習慣。
今日推薦開源項目:《開源指北》
今日推薦英文原文:《The Do』s and Don』ts of Code Reviews》
開源日報第1021期:《開源指北》
今日推薦開源項目:《開源指北》傳送門:項目鏈接
推薦理由:開源指北是10月啟動的一個項目,是一個開源新手教程,旨在為那些想參與開源的開發者們提供一個豐富詳實的操作指南,讓更多開發者認識開源、參與開源、愛上開源。目前已經完成了電子書修訂活動,在 Gitee 項目頁面即可閱讀。
今日推薦英文原文:《The Do』s and Don』ts of Code Reviews》作者:Mike Pesate
原文鏈接:https://medium.com/better-programming/the-dos-and-don-ts-of-code-reviews-77032ba3a30c
推薦理由:給代碼閱讀者和代碼作者的一些建議。

The Do』s and Don』ts of Code Reviews

Reduce team friction by having healthier code review cultures

Code 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 Reviewer

Here』s a list of behaviors to do and void when reviewing other people’s code.

Do』s

  • 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.

Don』ts

  • 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 Author

As the owner of the code, there are certain things you can do to make the review process easier on your team members.

Do』s

  • 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.

Don』ts

  • 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.

Conclusion

There 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.


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