Tidyteam code review principles

  Davis Vaughan

At Posit, we strive to write high quality code to ensure that you, our users, have the best experience possible. We feel that the code review process plays a critical role in delivering quality products, and in developing the skills of newer contributors, and we decided to make that process explicit through a tidyteam code review principles guide.

At a high level, this guide walks you through the perspectives of both the pull request author and the pull request reviewer, discussing various aspects of the process from both points of view (such as how to handle reviewer comments and how to write focused pull requests). Throughout the guide, we repeatedly tie back to three different patterns of collaboration, which reflect that each code review is unique and comes with its own set of expectations between the author and the reviewer.

We posted about this guide on Twitter and Mastodon a few weeks ago:

And we were happy to see that many of you are already finding it useful!

In particular, I’d like to shout out Hiroaki Yutani who created a two part video series reading through the principles in Japanese!

Internally, we’ve also been referencing this guide when reviewing pull requests from each other and from the community. For example, Jenny Bryan linked out to the section on creating a good pull request description when reviewing a bigrquery PR, and I internally linked a colleague to the section on GitHub Suggestions, which discusses how to batch multiple suggestions into a single commit.

We adapted these principles from Google’s own guide, and we encourage you to do the same thing with ours. If you work in a research lab or are on a software team at your company, then code review should be as important to you as it is to us! Feel free to modify these principles to suit your own needs, and if you do use them, we’d love to hear about it.