6 tips every code review author should know

6 tips every code review author should know


4 min read

I've submitted my fair share of code reviews at this point of my web development career and I've picked up a couple of tips along the way, so I wanted to share some of them with you.

1. Keep it small ๐Ÿค

Try and keep your code reviews as small as possible. This is better for reviewers as it makes it easier for them to focus on one or two goals. It's also better for you as it means you can push your code to production more often, giving yourself a sense of achievement.

As a code reviewer, there's nothing worse than getting a huge code review that takes days to go through. You'll find a reviewer's attention to detail will drop off after 60 minutes of review time, meaning you won't get the best out of your reviews.

By keeping your reviews small, you're more likely to get faster feedback and approvals, meaning you can ship your code more often. Win. ๐Ÿš€

In saying this, there are times where your code reviews simply can't be small. This may occur if you're making changes that affect multiple services or you're working with legacy code that can't be broken down as easily. This is fine too, these tips are just a guide to follow when you can.

As a frontend developer, I try to break down large stories into multiple smaller tasks, meaning I can submit smaller code reviews too. I often follow Martin Fowler's Keystone Interface method to achieve this.

2. Write a good description ๐Ÿ‘จโ€๐Ÿ’ป

Include a brief description in your code review where you give a summary of the changes made. This is very important as it gives the reviewer the context required to put themselves in the user's shoes while they review your code.

3. Include screenshots or recordings ๐Ÿ“น

If the changes you have made are visual then it's important to include screenshots, or even better...screen recordings. Similar to the previous tip, this gives the reviewer some more context into the changes you've made as they can link your code with what they see in your screenshots or recordings. As they say, "a picture paints a thousand words". I'm not sure if your screenshot will end up in any art galleries, but you can be sure they will benefit your reviewers. ๐Ÿ˜€

4. Give instructions on how to verify your changes ๐Ÿ‘จโ€๐Ÿซ

Depending on the code review, it's important to give your reviewers a way to play around with your changes for themselves. This is the number one best way to receive feedback, especially if the changes are visual. I've often found small issues during code reviews relating to how responsive a webpage is, which is something I wouldn't have spotted by looking at the code or screenshots.

On our team, we often use Heroku review apps which gives you a sandboxed version of your app. It gets deployed whenever we create a new code review. This has become a fundamental part of our code review process. However, most teams won't have this luxury so another good option is to ask the reviewer to checkout your branch and run it locally.

Here's an example of some instructions you could include in your code review:

  1. Checkout branch: popup-toast-notification
  2. Run app locally: npm start
  3. Go to the "Profile" page.
  4. Change your name.
  5. Click "Update".
  6. You should see a toast notification appear at the top of your screen.

5. Give reviewers enough time โฑ๏ธ

There is no point in requesting a large code review on the very last day of the sprint. It's important to give reviewers enough time so that they don't feel rushed or pressured into giving approvals. By giving reviewers the time they need, they can give you adequate feedback and it also gives you that extra bandwidth to make any requested changes.

6. Avoid scope creep โœ‹

As engineers, we always strive to develop the perfect solution. This can be good, but it can also lead to distractions in code reviews where reviewers will request extra features. How many times have you heard someone say "This is good, could you add this X feature to make it even better?". As the code review author, it's important to know when a request is outside the scope of the task you're working on. Getting feature request ideas is fantastic, but it's something you should discuss with your product manager and team members, and possibly create a new task for it. This could then be delivered as part of a separate code review.

Final thoughts ๐Ÿค”

That's it. ๐Ÿ˜€ Hopefully this article can help you improve your code reviews, but remember that these are just tips to guide you and so it's important to figure out what works for you and your team.

If you found this article useful then please give it a like, and if you have some tips of your own, feel free to leave a comment. ๐Ÿ™Œ

Want more? ๐Ÿ“ข

I mainly write about real-world tech topics I face in my everyday life as a frontend developer. If this appeals to you, then feel free to follow me on Twitter for more: https://twitter.com/cmacdonnacha

Bye for now ๐Ÿ‘‹