Stop trying to find problems with code reviews.

A simple guide to how expert and novice software developers can collaborate to get more value from code reviews.

Dear fellow software developer,

When I make a pull request, I’m not asking for approval. I’m not asking whether anything is wrong with the code. Or whether the punctuation is correct. Feel free to do any of these things, but it’s not what I’m after.

When I make a pull request, I’m asking whether you understand the change. You should know why it needs to happen and how it works.

And if you don’t, I need to make a change to clarify this.

As a novice, when you’re new to the code base, you may be hesitant to comment because, well… what do you know? You feel you first need to learn and understand the code before you can make any meaningful comments. How can you possibly tell whether something is wrong with the code? And the experts know what they’re doing, right?

On top of that you may want to be seen as the bright new guy. You don’t want to show your ignorance by asking silly questions.

But what better way is there to learn? Is there any code more worth learning about than code that’s being modified now? This is the stuff that matters. We wouldn’t change it if it wasn’t.

Moreover, now is the best time to try to understand this code: it’s fresh in the mind of the writer. All you need to do is ask why.

I understand you don’t want to be a burden to your teammates, but I have a higher goal. I want you to be an asset to the team.

I can suffer the delay to get there.

So when I make a pull request with a bad description and you don’t understand why the change is necessary: reject it. Even if I’m the expert.

When I write code with sub-minimal comments, which I honestly tend to do, and you don’t understand how things work: reject it. Even if I’m the expert.

By your questions I may discover I need to redesign parts because the components do not logically fit together. Or maybe there’s just too much magic. Being the expert, it’s sometimes hard to see what is easy to understand and what is not. But the time spent rewriting to make things clearer is time well spent: the code will be easier to learn, easier to debug, and easier to modify. Even for the expert.

Although I’m the expert, I know I can be wrong, and will admit it when it’s evident, despite my pride. But I’m much more willing to redesign when I discover the code is not as clear as I thought it was.

So, please, raise your hand. Ask why. Do not submit to my expertise, draw from it. I’m happy to explain.

With kind regards,

Wim Yedema.