Write a Chapter: "Code Reviews" about engineering-handbook HOT 1 CLOSED

Goals

Code review is about making software more efficient and improving bus factor. It's also about building community and establishing empathy with one's fellow developers.

To this end, we should shape code review practices such that people come out of a code review with:

• A feeling that they have learned or taught something about how to engineer software better;
• A feeling that they have strengthened a relationship with at least one fellow developer, contributing to an atmosphere of camaraderie and support;
• A feeling that they have contributed something meaningful to the software project in a timely manner.

Best Practices

• Prefer to review less than 200-400 lines of code at a time.
• Pair programming, in which the engineer less experienced with the codebase "drives" and the more experienced engineer "navigates", is an acceptable alternative to asynchronous code review.
• Synchronous code review via videoconferencing is an acceptable alternative to asychronous, text-based code review.
• When synchronously pair programming or code reviewing, consider making multiple commits during the process so that your learning process is documented.
• If you spot only a few trivial errors that you can easily fix yourself, consider merging the PR, fixing the errors yourself in a separate commit, and linking to said commit in the PR's comments. Be sure to encourage the contributor to look at the commit so they can learn from their mistakes, and offer to answer any questions they have about them.
• Respond to a pull request within 24-48 hours, even if it's just to say that you can't review the code for another couple of days.
• Consider using animated gifs and/or emojis in your comments, especially when thanking a contributor. This helps foster a positive emotional association with code review, as well as building team camaraderie.

References

• 11 proven practices for more effective, efficient peer code review - IBM DeveloperWorks
• On Code Review - David Humphrey's blog
• Adventures in Code Review and Pair Programming - Atul Varma's blog
• The following slide from a presentation on contributor retention that David Eaves gave at the 2014 Portland All-Hands:

from engineering-handbook.