What I’ve learned from code reviews: I need a little help from my friends
One of the most important emails I’ve ever sent to a client had a typo in the very first line:
Hi tony,
The mistake is obvious, right? ‘tony’ should have been capitalized. I proofread this email. I proofread it again, and then did it a bunch more. There are probably a dozen reasons I missed the typo — it was a long email with a lot of important details, it was time sensitive, there were a lot of other things on my mind that day, and on and on.
But I think there’s a simpler reason I didn’t catch the mistake: I didn’t ask for help. If I had asked someone else to proofread the email before I sent it, they likely would have seen the typo right away.
Writers and journalists know that proofreading blindness is real. Most of us are simply unable to see some of the typos and mistakes in our own work. It isn’t a matter of better focus or iterating more. The problem is with the way our minds work.
Mark Twain put it this way:
… you think you are reading proof, whereas you are merely reading your own mind; your statement of the thing is full of holes and vacancies but you don’t know it, because you are filling them from your mind as you go along.
In recent years I’ve learned this discipline from the programmers I work with. Rather than occasionally asking for a review from someone else here and there, they view this as an essential part of delivering anything important. Our company is filled with extremely talented, experienced software engineers who are religious about code reviews because they have been proven to be the best way to guard against logic problems and bugs in the software they produce. If you’re unfamiliar with it, a code review process is just what it sounds like: when someone writes some code, before it gets shipped a peer reviews it, asks questions, leaves comments, and points out issues the author of the code may have missed.
I don’t write code, but I do write a lot of words in my work. The artifacts I create are things like emails, reports, presentations, proposals, statements of work, agendas, and strategy documents. Because our company has a strong culture around code reviews, it has been natural for me to adopt this as part of my own workflow. Nowadays, any time I’m writing something important I’ll ask one or two of the people on our team to review it. This blog post itself is no different. Two other people I work with reviewed it, helping with minor fixes and offering suggestions.
Every important email I write now is drafted in a Google doc where I’ll ask my team for edits and refinements before I send it. Whenever I create any important documents or deliverables I’ll do my best to make them presentable but our team always gives them a full and thorough review before they get sent.
At first, I’ll admit, adding this step felt inefficient. It slows things down. You’re asking one or two other people to shift their focus from whatever they’re working on to help make sure your thing is good. But over time I’ve seen clear benefits. When this type of review practice is built into your culture it isn’t a distraction to review someone else’s work. It’s just the way that we as a team consistently deliver things that are of the highest quality.
Now, not everything deserves a second set of eyes. The email that says “Sounds good, see you tomorrow!” doesn’t hit the threshold for needing a second reviewer. There are no clear, concrete criteria for determining whether something should be reviewed other than your own internal gauge. I ask myself “Is this thing pretty important?” When the answer is yes, I ask someone else to review it. If not, I send it.
ChatGPT, of course, makes finding the smaller issues easier, and is an excellent proofreading tool. But for more complex, nuanced things like the accuracy of the content, or the overall tone and approach a real person is still the best editor.
So what happened with that big, important email to Tony? He was deeply offended and we never spoke again.
Kidding.
I apologized right away for the mistake. He was gracious about it and we moved on. Still, I wish I had asked for a review before I sent the email. Another set of eyes would have almost certainly caught the lower case ’t’ and spared me some embarrassment. Because even when you’re working with someone who is generous and forgiving, it still just looks bad.
