Candid-yet-humane peer reviews

We all understand that having someone double-check our work will probably make it better than it was before. This applies to a whole bunch of activities: a presentation to convince why a new feature is key to a product strategy, this blog post, writing postmortems, RFCs, code reviews, etc.

Although reviewing is mostly used to improve the quality of the work being done, in this post I will try to make the point that, in order to make the most out of these practices, you should save the discussion to revisit at a later time, as well as being empathic in the way you give your feedback.

Saving the discussion can be done by just having the conversation on something like Google Docs, Confluence or Gitlab. This way, you will have built a history library that is particularly useful when:

• Working with remote teams: if you’re all co-located, then you have the luxury of speaking face to face. Clarifying doubts is faster when two people are talking synchronously — rather than going through messaging ping-pong — and you can easily involve everyone who is relevant to the discussion. If this is not a reality and you have the challenge of going through a written conversation anyway, you better store it.
• There are lots of people involved: one of the key advantages of peer reviewing is that it helps sharing knowledge. You don’t need to know everything, you can just look it up when you need to.
• Contributing to a long-term project: the longer a project lasts, the greater the chance of the team working on it changing. When people start rotating, it becomes harder and harder to understand the context surrounding a certain functionality or decision, which may prove critical when trying to fix or enhance it.

You may notice that most of my claims are about sharing knowledge, and it’s no coincidence.

Given that you most likely take pride and are emotionally attached to your work, sometimes it can get awkward to present it out in the open for others to criticise.

This goes both ways though. It can be equally uncomfortable to provide feedback on someone else’s work, particularly if they are higher up the organisation’s food chain, more experienced, or maybe just recognised as key people.

Why would you risk looking ridiculous for raising a question that the gurus didn’t bother to? They’ve certainly noticed it too and would speak up if it was important, right? Not necessarily, no one is perfect.

Reviewing someone’s work can be a hard conversation, but if you do not feel empowered to discuss anything with anyone, then you would be better off not reviewing it at all because you’re just wasting your valuable time. Having this kind of culture is key to a company’s success!

The flip-side is when you have an opposing view, that you don’t mind sharing, but are not worried at all with how you deliver your message. On the other end of your comments is a person with their own background and emotional context. Two people can view the same comment very differently, but a single person can also view the same comment differently depending on who wrote it, the time of the day when it is read, whether the reader was feeling tired or not, different cultural backgrounds, etc.

In order to reduce the chance of anyone taking your feedback the wrong way, all parties involved should remember that:

• You are not your work: if I say something like “this change is useless, it makes things worse than before” this doesn’t mean I think that you are useless. However this still sounds rude, so…
• Be positive: “this change is not very useful” wouldn’t sound as offensive, would it?
• Be objective and use concrete examples: “this change is not very useful because it fails under scenarios X and Y. Even if it works under Z, that is a small gain for such a big loss.” This is more useful and much less offensive.
• Offer alternatives: knowing what’s wrong is good, but knowing how to do it right is great: “this change is useless because it fails under scenarios X and Y. Even if it works under Z, that’s a small gain for such a big loss. Do it the ABC way instead”.
• Give advice, not orders: you are not the owner of the work so, unless you want to do it by yourself, stop ordering the other person around. “What do you think of doing it the ABC way? While your solution is nice at A, this alternative seems better at B.”
• Compliment: if your work is getting heavily reviewed every day, it’s easy to start experiencing impostor syndrome. This is particularly common among new team members, not because they are not great at what they do, but because learning takes time. Have this in mind and be quick to hand out a sincere kind word once in a while: “This looks great! Nice use of X, I learned something today.”, or maybe “cool structure on the tests, it looks pretty easy to extend”.

This post is not specific to code reviews or technical discussions, but if you are an engineer working on a software company, you might be doing more peer reviewing than most people. Maybe try having some of these principles (speak up, be nice) on the back of your mind on your day-to-day.

We diligently try following some of these ideas and we feel that it has improved our team and the software we develop.