This post is not about how to publish a code review and instead assumes you already know how to do so. What this post is about is how to get people to pay attention or actually review your code review once you hit the publish button.
Assume nobody cares
Don’t expect people to flock to your code review. In fact, assume nobody cares. I know, that sounds a bit harsh but as Neil Strauss suggests, “Your challenge is to assume — to count on — the completely apathy of the reader. And from there, make them interested.”
I’ve seen both new engineers and seasoned engineers fall into the same trap. They send out a code review, one that lacks a clear description (see section below “A good description goes a long way”) and then the code review would sometimes sit idle for hours, sometimes day, and sometimes weeks.
Just remember this: people are busy. They too are writing code that they are trying to ship. So your code review essentially pulls them away from delivering their own work. That means it is on you to make their job as easy as possible and compel them to review your code.
One way to do gain their attention is simply by giving them a heads up.
Before publishing your code review, send them an instant message or e-mail, giving them a heads up. Or if you are having a meeting with that person, let them know that you are sending out a code review and ask them if they can take a look at the code review.
Bite sized code reviews
Anything beyond than 100-200 lines of code requires a significant amount of mental energy(unless the change itself is a trivial updates to comments or formatting). So how can you make it easier for your reviewer? Aim for small, bite sized code reviews.
In my experience, a good rule of them is submit less than 100 lines of code. What if there’s no way your change can squeeze into double digits? Then consider breaking down the single code review into multiple, smaller sized code reviews and once all those
independent code reviews are approved, submit a single code review that merges all those changes in atomically.
And if you still cannot break down a large code review into these lengths and find that it’s unavoidable to submit a large code review, then make sure you schedule a 15-30 minute meeting to discuss your large code review (I’ll create a separate blog post for this).
A good description goes a long way
I’m not suggesting writing a miniature novel when adding a description to your code review. But you’ll definitely need to write something with more substance than a one-liner: “Adds new module”. Rob Pike put’s it succinctly and his criteria for a good description includes “What, why, and background”.
In addition to the what, why and background, be sure to describe how you tested your code — or, better yet, ship your code review with unit tests. Also, be sure to also call out what is out of scope for this code review. By limiting your scope, you show that you are anticipating your reviewer’s critiques and explicitly detailing what is in scope reduces the likelihood of unnecessary back and forth exchanges.
Finally, if you want strict guidelines on how to write a good commit message, you might want to check out Kabir Nazir’s blog post on “How to write good commit messages.”
Overall, the article does an okay job describing the dos and don’ts but I would say that it’s a bit pedantic and I would argue that it’s not that important to “end with a full stop.” But still, a good resource for new engineers.