Tips for mastering code reviews at work

#careeradvice #programming

When you work on a small team (or even a large team) a significant part of your day is going to be spent doing code reviews. I think it is fair to say that I have reviewed more code in my life than I have ever written.

Code reviews serve a few purposes. You have the obvious reason of ensuring that all the code in your system is of a high quality and to identify bugs, but that is not really where the value comes from.

For me code reviews are an excellent way to share knowledge amongst the team and to discuss and promote best practices. It is also a great way to learn from others. You might see a good way of doing something that you haven't thought of before.

Code reviews shouldn't be the only place where teams can learn and share knowledge, but it is a good place to start.

Despite all the positives in favour of code reviews, they are an incredibly difficult thing to get right. As a software developer and generally an all round geeky person, I am not the most positive or tactful person on the planet. This means when it comes to writing code reviews I have to be extra careful with how I phrase my constructive criticism.

It's not always what you say, but how you say it!

The same also goes both ways. I remember as a junior developer receiving quite harsh feedback on my pull requests and taking it all too personally.

So let's have a look at giving and receiving feedback and some of the best ways to do it.

Giving Feedback #

How you give feedback during a code review is going to depend greatly on who's code you are reviewing.

If you are reviewing a senior developers code then a simple “Some more validation probably needed here” might be enough of a comment. For a junior developer however, you would want to add what requires validating and maybe show them an example in the code with how to implement it.

It is always best to assume the best in people. If they have missed something out then maybe they didn't know how to do it, or they simply forgot.

The key here is that your mindset should be the one of a mentor, not a judge. Here are some other key points to consider.

Maintain objectivity : Focus on the code itself rather than the individual who wrote it. As I said above you can tailor the amount of detail you provide based on who wrote it, but don't let your personal opinion of them sway your feedback. Equally, don't skimp on your review just because you think it is unlikely that they have made any mistakes.
Be specific and constructive : Instead of vague criticisms, provide clear, actionable feedback especially for junior developers. For instance, rather than stating “This function is inefficient” you might suggest “Consider using a hash table here to improve lookup times.”.
Prioritise issues : Distinguish between critical problems and minor stylistic preferences. If there is an issue with how the code works then of course point it out. If there is some extra whitespace at the end of the line is it really a big deal? When my comment is purely stylistic I will usually put a suggestion but still approve the review.
Ask questions : If you're uncertain about the reasoning behind a particular implementation, ask about it. Don't just mark it as wrong or inefficient but find out why it was implemented that way. Chances are there is a very good reason that you weren't aware of.
Acknowledge positive aspects : I must admit I sometimes forget to do this. If there was something your thought was done particularly well then say so. If anything, it helps to balance out any “negative” points you have raised.
Provide context : When suggesting changes, explain the reasoning behind your recommendations. “This is how we always do it”, isn't good enough.
Be mindful of tone : It is very difficult to get tone across when writing comments. This is where using suggestive language such as “Have you thought of…”, “I wonder if it would be better if…” and asking questions is usually better.

Remember, your goal is not to prove how smart you are or find every problem with their code but to collaborate with each other towards a better codebase and shared learning.

It is also important to note that you don't always have to find fault with their code. I work with 2 Staff engineers and generally their code is fantastic. Don't just nitpick because you feel you have to say something.

Receiving Feedback #

You would hope that anyone reviewing your code takes note of the above but of course that often isn't the case.

How the feedback is worded will of course depend a lot on the person doing the reviewing. If the person is mostly argumentative then this will likely be reflected in their comments as well.

Some points to remember:

Maintain an open mindset : View feedback as an opportunity to improve rather than as criticism. Every comment is a chance to enhance your skills or your code.
Separate yourself from your code : Critiques on your code are not a personal attack. Try not to take it personally.
Seek clarification : If you don't fully understand a comment or suggestion, then don't hesitate to ask for help. It could also be that the reviewer misinterpreted your code to start with.
Explain your reasoning : If you disagree with a suggestion, then explain how you came to your current solution. Given you have been working on the code, and they haven't there is a good chance you know something that they have missed. If your code is unclear you may need to add more comments.
Follow up : After implementing changes based on the feedback, let the reviewer know. Chances are you code will still need to be approved but if they have helped with some minor points, reach out and say thanks.
Identify patterns: Look for recurring themes in the feedback you receive. This can help you find areas that you obviously need to improve on. I always try to not make the same mistake twice. No-one likes having to repeat themselves.

Most people don't like to receive criticism but without knowing what needs to change how can we ever hope to improve? Always try to approach code reviews with a mentor/mentee mentality and hopefully this will help.

❤️ Picks of the Week #

🎓 Tutorial — HTML for People — Knowing HTML I think is a must for any developer. It is also a great skill for others to know as well. This looks like a great place to learn HTML if you don't know it already.

📝 Article — Germany's 49-euro ticket resulted in significant shift from road to rail — Whenever I have used public transport in Europe I am always amazed at how cheap it is. In contrast, driving in the UK is usually always cheaper and more convenient than the train. The UK could take some notes from Germany.

🛠️ Tool — Huly‚ Open-source project management platform — This looks like a really slick tool as an alternative to JIRA or Notion for project tracking. They have a main repository but if you are looking to self-host they have a separate repository to help with this.

💥 Comic — Ravioli-Shaped Objects — Got to love a good XKCD, this made me laugh.

🗺️ 3D Map — I 3D scanned the tunnels inside the Maya Pyramid Temples at Copan — This is quite cool. It is like Google Street View but with Mayan temples. Not everyone has the money or ability to travel to places like this so it would be good if there could be more of this.

📝 Article — The Internet Archive is back online — If you hadn't noticed the Internet Archive suffered a DDoS attack. I can understand, to some extent, hackers attacking corporate websites, but a non-profit trying to preserve internet history? I can only assume this was instigated by the government or some of the corporations who are suing IA at the moment.

📝 Article — FTC announces "click-to-cancel" rule making it easier to cancel subscriptions — Hopefully this will cause a change in how subscription cancellations are implemented and finally put an end to having to jump through 5 pages to cancel something. There are so many examples of underhand tactics like this.

📱 Tech — Amazon reveals first color Kindle, new Kindle Scribe, and more — The colour Kindle looks interesting, but it very much seems like first generation tech. It is nice to see book covers in colour, but it isn't worth the extra £100. If you want to read graphic novels a tablet with an LCD or OLED screen would be a better experience. I may upgrade to a Paperwhite though as my 2021 10th Gen Kindle is feels pretty sluggish at times.

🛠️ Tool — ArchiveBox is evolving: the future of self-hosted internet archives — Given the recent issues with Internet Archive it may be worth looking at an alternative. If you really want to make sure you have access to something online you are better off saving it yourself.

📝 Article — Winamp deletes entire GitHub source code repo after a rocky few weeks — I shared last month that the Winamp codebase was shared. Turns out there were a number of issues with doing that, and it has now been pulled.

📝 Article — Using Cloudflare on your website could be blocking RSS users — I use Cloudflare on my website and didn't realise this was an issue. I since turned off the bot protection so hopefully if you have had issues with RSS on my site you won't any more.

📝 Article — Adobe's new image rotation tool is one of the most impressive AI tools seen — This hasn't been released yet, but it looks like a genuinely useful use of AI. I don't use Photoshop a lot these days but their AI tools such as generative fill have kept me from jumping ship to Affinity despite the monthly cost. This looks like it might be coming to Adobe Illustrator soon.

📝 Article — Kagi Update: AI Image Filter for Search Results — I am a Kagi user, but honestly I am not 100% sure it is worth the cost. The results are still better than Google though. I shared last week how nearly all Google images for “baby peacock” are AI generated. This looks like a great addition to filter out fake images. I need to set up my own SearXNG instance and see if it is as good.