☢ Thoughts on software development, with an odd jaunt into language learning

Language in Code Reviews: How Not to Be a Jerk, Part 2

| Comments

Part 1 | Part 2

“Man, your code reviews are brutal!” says John to your teammates. He’s talking about you.

“Why do you hate me so much?” writes Steve in an email to you.

Sound familiar? You might just be Seth, one of the people most familiar with the project and gatekeeper of the code base. You’re not out to write “brutal” reviews, or make your colleagues hate you. You just want to ensure that only the highest quality code makes it into production, as bug free as possible.

So why do your coworkers think you hate them? When you write things like:

can’t you just do it this other way?

kill this

you can’t do that

They really hear:

“only an idiot would do it this way”

“why would you commit this?”

“aren’t you smart enough to realise that that won’t work?”

But that’s not really how you intended to come off, or you likely wouldn’t be reading this.

To try to understand more of John and Steves’ perspectives, read Part 1 of this article.

So why should you even care? Can’t John and Steve just grow a thick skin? Why can’t they just stop whining?

Because they’re human, and we all have extremely varying experiences, all of which drive how we interpret the behaviour of others. Some people will assign a benevolent tone, while others will just as easily assign a malevolent one.

When John and Steve interpret your comments negatively, their performance will decline. They will feel like shit, their productivity will drop, and they will resent working with you. They will not be able to thrive in such an environment, and your overall team performance will suffer.

Fortunately, you can fix it. And when you do, your teammates will think more highly of you, enjoy working with you more, and be friendlier to you. Their morale will increase, and their productivity with it.

It all starts with having the right tone. Without proper use of tone, it’s very easy to to lose the meaning behind the message.

When tone isn’t explicit, it’s easy to interpret it negatively. It’s also highly individual: John may read a comment as a friendly suggestion, while Steve reads it as an attack on his intelligence.

Writing comments without paying attention to tone is a default mode for most people. You must consciously insert tone when writing in order to prevent John and Steve from attributing a negative tone.

Fortunately, it’s a lot easier to fix than you would think. With some practice it will become more natural, and eventually you will be inserting explicit tone automatically.

The following techniques aren’t just applicable to just code reviews, but to all text-based communication you’ll use in daily life: emails, texting, chat, etc. Follow these suggestions and John and Steve will no longer think of you as a brutal gatekeeper:

1. You must focus on making your tone friendlier.

You can use the passive voice to remove a subject from the sentence, placing emphasis on the outcome of the action. This focuses on the problem, and not the person. Instead of “You must use four spaces for indentation”, use “Four spaces must be used for indentation.” Notice how the “you” has been completely removed from the sentence.


  • Bad: Kill this.
  • Good: Er, was this accidentally committed?

You can also use the collective “we” in place of “you”. For example, instead of “You must always re-throw exceptions here”, use “We must always re-throw exceptions here.” This de-emphasizes the original submitter as the target of the comment, and re-emphasizes that this is a team effort.


  • Bad: Can’t you just do it this other way?
  • Good: Unfortunately we need to it this particular way, or else the whizbob will become unstable and raise exceptions.

Use the passive voice, the collective “we”, and focus on the problem, not the person.

2. Ask questions.

Asking questions is also a great way to bring up an issue. They become responsible for the answer, and this gives them a chance to explain themselves. For example: Instead of “this will fail”, try “What happens if the gidget is set to 42?” It could be that they have a legitimate reason for submitting the code as it is.


  • Bad: You can’t do that.
  • Good: Are you sure that this is going to work? What happens if chunky_bacon is set to null?

3. Build good rapport with your teammates and they will integrate that into your tone.

Additionally, build rapport with the submitter. Eat lunch with them, play games with them (in person or online), get to know them. If this is something that is difficult for you, begin with a casual “got any plans for the weekend?” Show some interest in their response. If they answer with “I did some karate”, ask them about it. “Oh cool! How long have you been doing karate for? What do you enjoy about it?” Keep the questions focused on them, and don’t bring the conversation back to you. Bad example: “Oh cool! I’ve always wanted to do karate.” This brings the conversation back to you, and gives them the opportunity to lose interest.

Additional strategies you can use:

Avoid imperative forms. Make suggestions, not commands. Instead of “do it this way”, try “it might work better if we did it this way.” If you issue commands you will come across as demanding.

Prefer an informal tone over a formal tone. Instead of “This could be null here.”, try “this could be null here”, noting the lack of punctuation. Punctuation is still important, but the use of initial capitals and final periods can be safely discarded.

Don’t end your statements with a period. Studies have shown that ending your sentences with a period makes them come across as less sincere.

Use liberal use of emoticons and emoji. They explicitly demonstrate tone :) If you’re worried that the receiver will be annoyed by them, pay attention to how they themselves write, and tailor your level of emoticons to match theirs.

Don’t be terse. Terseness comes across as impatient and frustrated. Instead of “don’t do this”, prefer “if we do it this way, these bad things could happen”, or even better: “can you foresee any bad things happening if we do it this way?”

Admit that you may not understand everything. Instead of “don’t do this”, try “I don’t understand this. Would you be able to elaborate?”

Have clear guidelines and coding styles so that they don’t turn into an issue during reviews. Have an automated tool to check those styles before code is even committed.

Make it explicit when a comment is a suggestion: “it might work better if this implementation had rockets”.

Make it explicit when a comment is a mandatory change: “unfortunately we must transmit the the signal here, or the aliens will die”

Add compliments, acknowledgement, and gratitude: “Thanks, this looks awesome! Just a few things that I think we should change.”

Don’t write in anger. If you find yourself thinking “how the fuck did this get written?” Take a deep breath, step away from the computer for a few minutes. Calm down, come back, and write “I’m not sure this will run without throwing an error.” Otherwise you risk building resentment in the receiver.

Still worried that your colleagues might be interpreting your comments negatively? Grab them and go over your code review together, whether it’s in person or using Screenhero. Then you can explicitly add your tone in your voice.

With these guidelines, you’ll start to find that John and Steve are friendlier towards you, and their productivity will increase. These techniques will help you across all written communication, not just for code reviews. You will become a more pleasant person to work with, and that alone makes it worth the effort.

Language in Code Reviews: How Not to Be a Jerk, Part 1

| Comments

Part 1 | Part 2

“Jerk”, “Asshole”, “Ugh, what now?”, “Do it yourself!”, “Why are you so damned picky?”

Sound like things you’ve thought to yourself when Seth submits his review for your most recent pull request? Seth is the rockstar, know-it-all, pretentious, two-spaces-not-four and definitely-no-tabs-ever guy. He’s the gate-keeper of all code. He reviews all pull requests, and nothing gets into the code base without his approval. It’s his fault that you can’t meet your deadlines. Why can’t he just approve it so that you can move on to the next task?

Well, he could. But there are some very good reasons he wouldn’t want to.

It turns out that Seth probably isn’t as bad of a guy as you would think. The reason you feel this way could be aggravated by the tone, or more importantly, the lack of tone that was used in his comments while reviewing your code. That his comments made you feel shitty are a combination of multiple factors:

  • the tone (or lack of tone) Seth used
  • how well you know Seth
  • your rapport with Seth
  • your mood and energy levels when reading the comments
  • Seth’s mood and energy levels when writing the comments

All of these factors can combine to ruin the relationship you have with Seth. They can also turn your this-should-be-awesome day, into fuck-this-get-me-out-of-here day, where you struggle to crawl out of bed the next day, just to plop yourself in front of the computer, only to re-read the comments and spiral back into that foul and depressive mood again.

But there is a way out: Seth isn’t actually an asshole — it just seems that way due to how you’re interpreting his comments. Seth really just wants to make sure that the code that makes it into production doesn’t introduce any bugs.

Are you Seth? Then I recommend you read Part 2. For now, we’ll talk about how it is to be the receiver of Seth’s comments.

Tuesday morning. Opening Gmail, you see a thread containing comments from the pull request you submitted yesterday. It’s from Seth, of course. You grit your teeth, wondering if you should put your mouthguard back in. At this rate, your molars will be ground down by the time you hit forty. Tensing your muscles, you open the thread.

kill this

this must be a typo.

this does not look good to me. Why was this done?

Yup, sounds like Seth is his normal, moody self. But wait, there’s more:

can you not just change it so that it uses attributes?

why can’t you just do it this way?

can you explain this change?

And you’ve got your daily standup in ten minutes! Now you’re thinking that it might just be best to call in sick and play video games all day.

Does this sound like you? Even just a little bit? Read on. Even if it doesn’t sound like you, you may run into this in the future, so you may want to keep these things in mind.

It’s very easy to see Seth blaming you for this. “Can you not just do this?” “You must surround function parenthesis with spaces”. It’s all your fault, and Seth is making sure that you remember that.

Well, not really. There could be an entirely different side of this story: Seth is in a rush, and only has a few minutes to conduct your code review, one of many that he has to get done every day. It shouldn’t come as a surprise that his comments are terse, such as “remove this”. Seth doesn’t really hate you at all, he just wants to get the code review over with so he can go on to fix the issue that brought the database down last week.

How did this conspire to ruin your day in the first place?

Well, Seth’s comments lack tone. When they lack tone, it’s very easy to insert a tone that matches your current mood, or one that reflects how you think Seth feels about you. If you think Seth hates you, you will interpret it in that tone. If you’re feeling down or frustrated, Seth’s comments will seem like he is frustrated too. And after you hear those tones once, you’ll likely interpret his future comments in similar tones.

“That’s great, but what can I do about it?” you ask.

Well, it turns out that you can change how you interpret such messages. In Learned Optimism, Martin Seligman writes about a technique that people can use to help stop interpreting comments as personal, general, and permanent, and interpreting them as impersonal, specific, and temporary. Reginald Braithwaite gives a much better overview here. Go read it.


You can learn to read such comments in a more positive, friendly tone, but it also helps to build a good rapport with your reviewers. If you haven’t met them in person yet, make it a priority to to do, if possible. Once you get to know someone in person, it becomes a lot easier for you to transfer their in-person personality to their tone-less comments.

If it’s not feasible to meet them in person, try to organise things you can do together online. Play some games online together, with microphones on, or have a “happy hour” for the team, where everyone jumps on hangouts and has a virtual drink together.

Also if you’re comfortable with it, the best course of action may be to try to talk to Seth directly. Don’t open with a bold statement like “Why do you hate me?” That implies that Seth actually does hate you, when it’s likely far from the truth. Try something like this: “When you do X, I feel Y, and that makes me Z”. Following that formula focuses on your feelings and the impact it’s having on you, rather than attacking Seth. Try it out: “When you say ‘kill this’, that makes me feel like you’re frustrated with me, and that makes it more difficult for me to come into the office.”

If that sounds really daunting to you, or you don’t feel comfortable enough with Seth to talk to him like that, you may try an indirect approach. Post the second part of this article in your team’s chat, suggesting that everyone read it. When Seth comments on another team member’s pull request, point out to him how negatively his comment can be read, and encourage him to add explicit tone to his posts.

The key take away here is that you don’t want to attack Seth; That will only make things worse. Focus on how it feels to be on the receiving end of those comments, and Seth will be able to show a bit more empathy. Encourage, don’t disparage.

You may also feel shame that Seth is pointing out something that you know you could have done better, but you have to take it into context: You may not consider it to be your best work, but it was the best effort you could give at that time. If you’re under pressure, in a time crunch, working overtime, distracted, sick, or otherwise exhausted, you’re not going to be able to do your best work. In this situation, it’s best to view it as a chance to improve something that you did before, and to know that the next time you do something like that, it will be caught by Seth. It’s also a chance for you to be grateful that such code did not make it into production.

How can you continue to work with Seth? In summary, here is how you can make it more enjoyable:

  • Build rapport: spend time in other fun activities; meeting in person; if remote, play games or hangout online
  • Learn how to control how you read tones in messages (helpful even beyond this scope)
  • Empathise with Seth: he wants the code to be bug free
  • Communicate: talk to Seth about the tone in his comments

As a reviewer, Seth has a hand in it as well. He can spend just a little bit of effort to add some tone to his comments. In part two, learn how to not be a jerk when doing a code review.

Valued Leadership Qualities

| Comments

Here are the qualities and characteristics that I find important in leaders, and consquently, the values I would strive to show myself as a leader. I consider this a work in progress, and will expand/edit it as I grow. These are in no particular order.

Patience: Impatience adds stress and anxiety to team members, who otherwise do their best work when relaxed and comfortable. Team members should feel confident in admitting mistakes (after all, everyone makes them), and should not be punished for them.

Listening: One of the most important skills, in my opinion. A team member should feel comfortable bringing any problem to a leader. If one does not listen, that level of comfort is difficult to establish. A leader should not interrupt others when they speak, and should seek to understand what the team member is trying to communicate, rather than waiting for their turn to speak.

Humility: I believe everyone can learn something from anyone else, regardless of their age, experience, or background. Keep an open mind, and be open to new surprises. Leaders are not better than/superior to others.

Appreciation: A leader should show appreciation to all around them, but especially their team members. A lack of appreciation makes others feel unimportant, decreasing their morale and motivation.

Encouragement: One should encourage, not disparage. Reward the good behaviour that they observe by showing appreciation. Encouragement helps team members go further, and increases motivation.

Vision: She should know where the team wants to go, and be able to help the team get there (even if they themselves don’t know how). This includes both short term and long term goals.

Focus: A leader should help the team focus their efforts, steering them in the right direction so that they can strive towards their vision.

Mentorship: They should help those around him grow, challenging them to expand and strengthen their skills, both professionally and personally.

Interest: Take a genuine interest in team members, building rapport with them and supporting them. There should also be a genuine interest in the problem domain, and a leader should seek to grow their expertise with it.

Problem Solving: A leader should be able to help solve the team’s problems, whether those problems are within the team (ie. conflicts) or without (ie. technological or organizational blockers). Solving these problems lets the team focus on achieving their vision, without being distracted by other issues. A leader can help identify these problems, and also propose solutions and drive their resolution. These problems can be anything: technical, organizational, environmental, and personal.

Collaboration: Getting the team working together is more effective than issuing orders to team members. People feel powerless when commanded to do something. Collaboration gives the power to the team, regardless of seniority or title. A leader should do what they can to encourage such an atmosphere. When a problem arises, the focus to solve it is on the problem itself, not to lay blame on those involved.

Tolerance: A leader should foster an environment of tolerance, allowing team members to be themselves in an environment free of prejudice and oppression. This means immediately tackling issues such as (but not limited to) sexism, homophobia, racism, bullying, or antagonism.

Feedback: A leader is able to give feedback in a constructive and useful way, helping team members grow, rather than criticizing them and making them feel resentful.