Nonviolent Code Review
By: Valtteri Laine
Tags: Giving Feedback, Feedback, Programming, Nonviolent Communication, Code Review

Are you left frustrated after code review? Does it feel like the reviewer is being too strict and just wants to do things his way? Or maybe you feel that you can’t really say what you think?

After being on both sides of the table, I feel that I might be able to give some advice. Keep in mind that code review can be a struggle for both sides, and it helps to understand each role.

Programming is often a team effort

Advice For Reviewing

Write a Summary

Chances are there are always a few tiny things wrong in a pull request. Somewhere a variable name is unclear, indentation is off, or a line of code is too long. It is completely normal and almost unavoidable. Personally I will comment on these things, even if they feel small, as they will improve readability.

Challenge is that when you comment on the little things, it easily creates a feeling that the pull request is trash, even though it might complete the given task, and may even do it well. If all you have to say is a few style errors, then the pull request is in fact excellent!

To solve this mixed message, I recommend writing a summary at the end of the PR review. I don’t just click “Approve” or whatever flag there is to mark the PR as mergeable. I make sure to write at least a single sentence summary. For example, “Well done! A few small styling improvements could be made, but other than that looks good! After those have been fixed feel free to merge.”

This is a good place to sneak in some positive feedback, without it sounding forced or fake. It also makes sure that a pull request doesn’t get stuck in limbo, where the PR author it isn’t sure what the reviewer wants. Does he want to review it again after I fix the issues he mentioned? Do I merge it, or does he? Was the PR any good? These are just some questions that the PR author might have, that you, as the reviewer, should try to answer proactively.

Choose Your Words

We have plenty of synonyms in our disposal, and we should be careful which ones we use. Synonyms transmit the same information, but are different on an emotional level. How specific words make us feel is highly individual, but I believe that at least in the same culture we can make some generalisations. Here are five positive alternatives for words that can sound discouraging.

Say challenge, instead of problem. Problems just sort of exist. You complain about them, and maybe something is done about it or not. However a challenge is a chance to rise to the occasion. It is a possibility to prove that you are worth your salt, and to show off your problem solving skills. Either way you tackle the problem or challenge, but you know I’d much rather challenge myself than just fix problems.

Say and instead of but. “Well done, but…”, “Well done, and…” See how different those two sentences feel? Even though I only changed one small word. Saying “but” makes the listener forget about everything that was written before the “but” word. It can completely erase any nice words, and even make them sound fake or forced. So instead of saying “Well done, BUT the indentation needs to be fixed.”, say “Well done, AND if you fix the indentation it will be even better!”.

Say excessive or leftover instead of useless. Useless is a harsh word. It means that there is absolutely NO use for a piece of code. This is simply not true. Thomas Edison found 1000 ways how to not make a light bulb. Had he not recorded his 1000 attempts, he would have not remembered what he had tried and ended up repeating himself. So even code that doesn’t work is not useless. It is there to remind you how to not do things, and also creating it taught you and maybe others. We may not wan’t the code in production, so call attention to it by saying that this is leftover, excess or maybe extra code. In the end the code will be removed all the same, whether you called the code useless or extra.

Don’t say “This doesn’t make any sense”, say “I don’t understand this” or “This could be more readable, because…”. Saying “This doesn’t make any sense” shifts the blame for you not understanding to the codes author not writing code that you can understand. You could have very good reason to not understand it, but nevertheless you don’t understand it. The codes author may not understand it either. All of these options end up with the author of the code explaining to you how the code works, or refactoring the code to make it more readable. However by saying “I don’t understand this” you are showing vulnerability and fully owning up to your inability to understand the code, instead of blaming the author. It also makes it obvious to the author that codes readability is not good and should be improved. I mean you are a smart guy and even you don’t understand this? Man, this code needs some refactoring.

Say feature instead of bug. Actually no, don’t say feature instead of bug. Scratch that.

Explain Your Feedback Proactively

It might be valid feedback, and needed feedback, but unexplained it goes to deaf ears. If you say that the code is not testable, or it’s incomplete, too complicated and so on, you should also state why it is that way. Pointing out concrete examples from the pull request will help to drive your points across. People see things differently and aren’t mind readers.

Unexplained feedback can also feel lazy, teasing and unfounded. The reviewee might think to himself “Why should I bother to change the code, if you didn’t even bother to explain what is wrong with it?” If you put effort into your feedback, the reviewee will feel compelled to put effort into his code.

If feedback is given without proper explanation, it can get personal. The person receiving the feedback has no idea why you are giving it, so imagination sets in. “Did I look at him wrong at the coffee machine? Do I ask him too many questions?” Explain your feedback and do it proactively. Nobody want’s to be the guy to ask “Why?” on every single comment you posted on a pull request.

Give the benefit of the doubt

Chances are you are reviewing code that you do not understand perfectly. Often I don’t even understand my own code perfectly. This is why it is always important to give the benefit of the doubt. Do not state that something doesn’t work if you aren’t absolutely sure about it. It will save you from looking like an asshat.

Instead you can ask, “Are you sure this works?”, “What happens if the value is undefined, or something else unexpected?”, or you can simply ask the person to write unit tests for the piece of code. All of these are valid points, and shouldn't be an issue.

If the piece of code can be easily isolated, I will replicate the situation in an online website like Repl.it, and share it with the pull request author. Easily executable code snippets are really good at explaining things.

Do Pair Programming, Instead of Doing the Other Person’s Job

If you are reviewing another persons code, and the code just wont do, I would advice to resist the urge to code it yourself. If you do, what do you achieve? The task is done, but you have now given the reviewee a way out of difficulties, and likely he hasn’t learned anything in the process. Think about the long term.

It is tempting, and even Bill Gates has admitted to being guilty of this in his youth. He eventually had to stop when the Microsoft grew large enough. If you are a regular human, and only have 24 hours in a day, you can only do one job well, and that is your job.

If you feel the urge to recode someones code, use it as a cue to do pair programming with the person. Pair programming is a great way to share knowledge. This way two people are already familiar with the code when it’s done, and code has already been peer reviewed. The more knowledgeable person shouldn’t be coding, instead he should be conversing with his pair who does the coding. Pair programming is a huge topic and you can read more about it here.

Advice for Being Reviewed

Pull request review can be emotionally difficult, especially for the reviewee. You worked hard for days or even weeks for a strict deadline and for what? Just to have your code stuck in PR limbo? Maybe you had several “Aha!” moments, and maybe you did a dozen things well, but did the reviewer even notice?

Remind Yourself Why Code Review Exists

Reminding yourself why you are putting in effort and time into code review helps. If you think you are going through code review for no good reason, you will be frustrated.

So why do we do code review? Code review helps with readability, maintenance, code reuse, finding bugs, error handling, spotting side-effects, consistency, with test coverage and so on. There are so many good reasons to do code review. The benefits are not always short-term, but whoever inherits the code will notice.

Code review is a learning opportunity, that you should take advantage of. As the pull request author you also leave comments in a pull request for the reviewer to find, and share his opinion on.

You can read more about why code review is important from here.

Don’t Expect Positive Feedback

Giving positive feedback doesn’t happen automatically to most people. Some people try to sandwich negative things with positives (aka. the shit sandwich). Pairing positives with negatives, can make you associate the positive feedback with the negative feedback. Especially if you only give them together. Whenever I hear “It looks nice, but…”, an alarm bell goes off in my head, no matter what the person is actually saying.

If you feel that you did something well, you can always draw attention to it. You can ask “What do you think about this?”, and hopefully you will hear the other persons honest answer. Worst thing that can happen, is that you will have a normal conversation about it. Maybe he will notice the solutions brilliance, maybe not, but now you know what he thinks about it.

Personally I believe there is value in gratitude and positivity, but even greater value in hyper realism. If something isn’t good, then I wont say it is. Forced positive feedback feels dishonest, and can make things worse. I share positive feedback when it feels natural, but if it feels forced, then I typically don’t. Seeming dishonest is worse than seeming negative, because if you seem dishonest even your positivity will be negative, and it will affect your believability across the board.

Have a Conversation

If the reviewer has given you feedback that you don’t agree with, you can always ask him to explain. You can ask “What do you mean?”, “How is it better?” or simply “Why?”. If you are worried about getting on the reviewers nerves, I would recommend saying: “I’m asking because I don’t understand. Could you explain it to me one more time?” It shows willingness to learn, patience and it also doesn’t have a hint of aggression or challenge. Instead it shows that you trust the other person enough to be vulnerable. No-one sane could be mad about or refuse this polite request. If the other person still gets mad, you need a different reviewer.

It can also help to think what is the root motivation for the reviewer to give this feedback. Likely it isn’t personal. The reviewer could be worried about the project. Is his sense of security being fulfilled? Does he trust that the code actually works the way you promised? Both of you are responsible for the solutions you are making. When something goes wrong neither of you will take full responsibility for the mistake, instead you will share it. Your problems are his problems, and vice versa.

Code review is teamwork, and the best thing you can do is keep the conversation polite and not to take it personally. After all it is you two versus the challenge, not you two versus each other. If you feel that the other person is using his position to harassing you, talk to someone you can trust.

Summary

There you have it! Most of these topics touch on social skills, instead of technicalities. Personally I’ve found that most issues could have been avoided by having a good conversation, rather than just having technical expertise. Both are required to be a professional software developer.

What advice would you give to someone struggling with Code Review? I would love to hear from you, and feel free to share your opinion of this article, whether you liked it or not.

Thank you for reading!