The art of reviewing

I wouldn’t be exaggerating if I say that we spend at least one hour a day reviewing each other's work. Why so much? The answer is clear. Through peer review, we maintain the quality of our products. On top of that, we learn a lot from it as a feedback receiver and reviewer. But completing a review is no small feat. You’re required to constructively criticize the work of your peers, some of which has taken blood, sweat, and tears. How do you make feedback constructive and clear? We discuss three peer review methods, including our favorite. 

Solutions, solutions, solutions 

To optimize the quality of your work, profound feedback is needed. One way to do peer review is what I call the know-it-all method. You make the code or text your own. You have seen every word, every sentence, every interpunction or every string multiple times, and suggest alternatives for parts that don’t meet the quality standards. Sometimes this is accompanied with an explanation as to why you’ve changed it. 

In the past, I used this method. Look at how I changed the introduction my colleague, Jeroen, wrote for his article, “Why we don’t do overtime.” 

Do you recognize this: you’re in a project with a tight deadline. You’re putting extra hours to get to the deadline. After some days of overtime, you get home late and tired, eat unhealthily and you go straight to bed. The next morning you get up early, still not refreshed from the short night. Get yourself together.  Be strong and heroic and get this deadline. You promise yourself next time will be different. That you’ll plan better, make those improvements you skipped this time. You will leave the office on time and eat with your family or have a drink with your friends. Only the next time there is another important project with a deadline. And it repeats itself.

_{Draft introduction of the article, “Why we don’t do overtime,” written by Jeroen.}

I suggested to change it to this to make it more appealing as an introduction:

In most jobs, more often than not overtime is expected. We don’t believe overtime is the solution to getting work done and meeting deadlines. Over and over again. In fact, we think it’s counterproductive. That’s why we wrap stuff up after an eight hour day, a regular working day in the Netherlands. 

_{Final introduction of the article, “Why we don’t do overtime,” written by Jeroen.} 

In my opinion, Jeroen’s introduction was too long and consisted of information that was repeated in the body text. I spent quite some time to come up with a new introduction, and Jeroen accepted it. 

Replacing your own work with other people’s work reduces the feeling of complete ownership.

What went wrong? I immediately gave the solution. This method of reviewing is no better than just asking for approval. Of course, as a feedback receiver, you get a glimpse of the reason for the change. But by not rewriting it yourself, you miss the opportunity to improve your writing skills. Besides that, replacing your own work with other people’s work reduces the feeling of complete ownership. It doesn't feel like your work anymore. Moreover, their levels of insecurity can increase, which can cause poorer quality of future work. The know-it-all method can also facilitate something else entirely: you take the feedback for granted and are not critical of it anymore. This is something we don’t want either because every point of feedback should also be a learning opportunity. In our opinion, reviewing the feedback you receive is key to your own development as a (front-end or back-end) developer or writer. 

Quick and dirty 

At the other end of the spectrum, you have the quick and dirty method. This consists of asking your peers to approve the work you’ve done to get to the next step of the process. Actually, you don’t want feedback. You just want something online because: 

1. You’ve developed the piece of code together (pair programming). 
2. It is such a minor change that nothing can go wrong. 
3. You feel time pressure and comments cause a delay.
4. You’ve discussed the solution with a colleague and implemented it afterward.

In the case of reason A and B, the quick and dirty way is permitted. In our daily work, we do it quite often. It is just part of our process. But this doesn’t count for reason C, D, and other complex tasks. In fact, an extra pair of eyes is quite necessary because the devil is in the details. 

Meet in the middle 

The two mentioned peer review methods aren’t ideal in terms of learning. That’s why our beloved method meets somewhere in the middle. In our opinion, valuable peer feedback:  

• Is constructive. We treat colleagues and their work with respect. 
• Makes you think. It helps you reflect on your work and encourages you to think of other solutions. 
• Consists of questions. Why did you do it this way? What is the reason for this setup? Did you think of option X and Y instead of only Z?
• Makes it possible for people to process it themselves. It points them in the right direction, without giving the whole solution. Although, sometimes it is very difficult to hold back, especially when it comes to minor mistakes. For example: inconveniently named functions and variables (code) or grammar mistakes (content). 

We see peer feedback as a conversation starter. Joan, a Back-End Developer at Easy LMS, explains: “I don’t reveal the entire solution, sometimes only a part, but I mainly discuss how an alternative can be achieved by refactoring. And this sometimes means just literally sitting next to someone to walk them through, instead of playing ping pong via GitHub or BitBucket, the tools we use for code reviews.”

“What I also do sometimes: I offer multiple alternatives and leave it up to the feedback receiver to decide which alternative suits them best. It’s a brain teaser because several options have to be carefully considered.”

_{Examples of a code review conversation in GitHub.}

According to Joan, conversational feedback is not always needed. It depends on the type of code. “Suppose someone has accidentally put a (security) vulnerability in the code, then it is clear that it must be removed. Of course, I will explain why it should be removed and how you can avoid it from now on, but it’s not an ideal moment for a big conversation. Then the know-it-all method suits better.”

Anna, our Implementation Consultant, and native English speaker, checks all English texts before they go online and applies the conversation method as well. Just a few weeks ago, she corrected grammar mistakes herself. Now she refers more often to our Style Guide, so people can fix it themselves. “And when someone switches tenses all the time, I just ask them which tense should be used.”

Takes more time, but it pays off eventually 

The more you process feedback yourself, the better you get, and the less time it takes to deliver the right quality next time.

This last method of peer review takes a lot of time, especially in the beginning. That’s probably one of the reasons why we sometimes fall back into our old, comfortable habits. But we tell ourselves over and over again: the more the feedback makes you think and the more you process it yourself, the better you get at your job. Then, it will take less time to deliver the right quality next time. The benefits are twofold. Ultimately, it will also take the reviewer less time to review. Even then it is important to continue being critical and to provide valuable feedback because it helps with:

• Involving your colleagues in your daily work. There are no isolated islands of work. 
• Increasing confidence in the work that you create because someone else thinks it's worth looking at.
• Improving the quality of the work. It is a long-term investment that prevents (costly) mistakes. 

This article was reviewed in the conversational way 😉.