If you use a cloze-style (aka. fill in the blank) question when learning vocabulary, you eventually come across a synonym. For example in German, you have wohnen and leben, and they mostly mean the to live. You can put it in the card as superscript:

Front: Wo [[live]]^lebst du?
Back: wohnst

There are a couple problems with this approach.

First, it’s a bit unnatural to type. Would you rather type “Wo wohnst du?”, or “Wo live du?”.

Second, it doesn’t work well if you want to generate text-to-speech (TTS) audio samples en masse with AwesomeTTS. If you pass this card to AwesomeTTS, it will generate audio with input “Wo [[ live ]]lebst du?”, which generates nonsense. What you want to feed it is: “Wo wohnst du?”

What if we use the built-in cloze template? Then the card would look like this:

Text: Wo {{c1::wohnst::live}}^lebst du?

This is a bit more natural to type (start with “Wo wohnst du?” then add the cloze, then add the synonym). Anki has shortcuts for adding a cloze (⌘-C / ALT-C) and for adding superscript (⌘-SHIFT-= / ALT-SHIFT-=), making this a bit easier to type.

But this doesn’t solve the second problem. If we feed this to AwesomeTTS, it will generate audio for “Wo wohnstlebst du?” which is still nonsense.

My solution: Put synonyms in another field.

Text: Wo {{c1::wohnst::live}} du?
Synonyms: lebst

This is the easiest to work with, IMO. Once you add the cloze hint, you can hit TAB and then type out the synonyms. Also the Text field can be fed directly to AwesomeTTS and it will work as expected.

We can modify the template to show the synonyms following the cloze entry, so it looks exactly like it did before.

Here’s the front:

{{cloze:Text}}
<br/>
<br/>
<span id="synonyms"><sup>{{Synonyms}}</sup></span>

<script>
  var synonyms = $("#synonyms")
  synonyms.insertAfter($(".cloze"))
</script>

And the back is almost identical, just include the extra note:

{{cloze:Text}}
<br><br>
<span id="synonyms"><sup>{{Synonyms}}</sup></span>

<script>
  var synonyms = $("#synonyms")
  synonyms.insertAfter($(".cloze"))
</script>
<hr>
{{Back Extra}}

Voilà!

I’ve created a sample deck that contains the above template and note.

The original idea for this was provided by Vocabulary Labs course, which I highly recommend!

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.

Example

• 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.

Example

• 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.

Example

• 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.

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.

Optimism

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.