So you are using git? Awesome. But then comes your first pull request (PR). What should you expect? Or maybe it is time to do your first PR review on someone else's code. This too can be daunting. No one likes to be criticized, but when there is something wrong in the code, it needs to be brought up.

I have struggled with this over my near 20 years of programming, first in the form of code reviews, and now in the form of pull requests. I have done the Google searches, read leadership articles about it and most of all struggled through it myself. Surprisingly, this seems to be a set of skills that are not generally well developed in post-secondary computer science type programs (at least in my experience). Anyways, maybe through my pain and experiences you'll find something that helps.

Principles

I like to approach code reviews with some principles in mind. I have found that these principles help the process go smoother no matter if you are the reviewer or the reviewee.

Principle 1: Be flexible

Go into a PR review with an open mind. Coding is as much art as it is science. One thing I have learned over the years is that technical correctness and pedanticness do not necessarily equate to good code. For example, does it really matter that your variable names all adhere to a pattern if the code is too slow and frustrates a user? Further, I remember a time where a developer was so focussed on writing good code with an ORM, that they thought it was awesome. The problem was that this was a batch process that had to copy gigabytes of data from one database to another. Using a transactional ORM was basically an approach fraught with issues, as it needed to load each record into an object to transfer it. An alternative approach would have used a bulk transfer tool to stream the data between databases and minimize the memory overhead. However, this developer was so convinced that because his elegant code was perfect, that when the issue was brought up, he couldn't see past the technical correctness of his code for the real problem, so it went to production. Shortly, we started to see memory issues as the datasets grew and the process started to fail...

On that note, also remember that we all have different ways of approaching problems and different styles of coding. In the end if there are multiple styles in the code base, does it really matter if the maintainers can understand the code? For example, does it really matter that you missed a leading underscore on an instance variable if the rest of the name is intuitive to the team? Or does it really matter if your opening chicken-lips (AKA curly brace or { ) is on the same line as your method declaration or on the line following it? The code still compiles and executes the same regardless...

Principle 2: Be curious

When under going a PR review, approach it as a learning opportunity. Both sides of the PR have an opportunity to learn. Instead of being critical and saying something like "This is wrong because X", instead ask a question like, "This is an interesting approach, what led you to go this route?" You can also go one step further and add a suggestion if you truly do think that something is broken. For example, "Your logic for processing this collection is nice and simple and solid. I wonder, though, could we improve it however by using the new .ForEach() collection method so the runtime engine can optimise and process the collection in parallel or multi-threaded?" Doing things this way gives credence to what the person did, but asks open ended questions to start the dialog about how things can might be improved.

Principle 3: It ain't personal

When working in a team, it is important that everyone realize that code is just code. Try not to treat it as an extension of the author (yourself or others). While it is logical to feel this way (someone wrote it after all, using their own brains and ideas, so there is an amount of reflection of self in there). However, those feelings do need to come second to the goal of the team and the purpose of the code. For example, I may pride myself on a clever trick in my code, or what I think is a particularly elegant way of writing something. However, if that code is hard to maintain for others, or is super slow for an end-user, it probably needs to change. I have encountered far too often developers that measure self-worth by what others think of their code (and I will openly admit that I have been one of these myself in my mid-career, but I think I am mostly past that now). Thinking this way can be truly devastating to all involved. Do yourself a favour and figure out how to move past the code being "yours". My work life has been much happier since I figured this out. Also, I find that people approach me more easily and freely now.

Principle 4: Don't forget the human element

I have found that in this day in age, we often put technology between us and others. Texting instead of chatting in person or making a phone call is one example of this. Don't get me wrong, text messages and chat systems like Slack are amazing and bring huge benefits, but we often forget their limitations and downsides. People are inherently social animals and inherently behave differently in near-to-face situations.

Another good example, in the context of PRs and code reviews, is that many git systems (Github, BitBucket, Gitlab) allow comments to be placed on and throughout PRs. This, however, can cause problems because these systems remove the face-to-face and PR reviews are inherently about "checking up on someone's work". So much non-verbal communication and other social cues are lost when you only use these systems. Don't get me wrong, things like this are useful and have their purpose, we can't forget that we are social beings. I suggest knowing your audience and adjusting (see Principle 1: Be flexible). I have worked with people who are fine with only using this system of communication as they don't take offence if something could be taken not as intended. Yet, on the same team, I have worked with people for whom this doesn't work very well (they always seem to feel attacked). What I have found is it is important to know what works for different teammates and adjust. When I am not certain how a teammate is likely to react when I review a PR, I generally do the following:

1. I use the comments system as a way to mark issues, including a brief description of what the issue might be (I heavily apply Principle 2 when writing these descriptions). This is simply so that nothing gets forgotten and so that we both can find the affected code quickly. Nothing more.

2. When I have done my review, I sit down with the person, in person or on the phone, and step through where my concerns are in the PR (I am also careful to not just read the comment to the person...something about having the person right there listening to me, autocorrects anything potentially offensive in my written words). Again heavy application of Principle 2 has proven to be useful here.

In Summary

So there you go...my approach to PR reviews both as a reviewee and reviewer. Basically, it boils down to being humble and treating it as a learning opportunity.

In the immortal words of Wil Wheaton, "Don't be a dick."