A blog on software engineering by Trevor Brown

The Best Book on Code Reviews

The Best Kept Secrets of Code Review by SmartBear software has influenced how I create pull requests and perform code reviews more than any other book I have read. I read it back in 2015 and a lot of the findings from the studies in the book have stuck with me.

The book was written in 2013 and the study in it was done in 2006 and only studied software development in Java so even back when I read it it felt a bit dated. I really appreicated the empirical approach it takes to studying code reviews and I’ve personally experienced the benefits of the advice given in the book.

I’ve adapted what I read in the book to suit my more modern workflow with web-based pull requests and asynchronus code reviews. Based on the book I’ve come up with a few "rules" for my pull requests. Note that these are for tailored to me when I am working in Elixir, Erlang, and Ruby:

  • Keep pull requests under 400 lines of total changes. Ideally under 200 lines. Anything more and reviewers will not be able to remain focused on all the changes present (page 80 in the book).

  • Do a thorough self-review of code changes prior to requesting review of a pull request (page 84 in the book). During self-review:

    • Fix issues identified. This helps eliminate the low-hanging fruit of bugs and formatting issues that other reviewers would find and frees them to focus on more subtle issues that may exist in the changes.

    • Annotate the pull request with comments explaining why the decisions made and why each code change is necessary.

I hope this post has inspired you to look past the dated environment in which the code review studies in it were performed and read this book.

Note: I am not receiving compensation for this blog post and I am not affiliated with SmartBear software. However the book is behind a registration form you’ll have to fill out.