How to Give Code Reviews Without Getting Burned (Figuratively... Mostly)

Fearing Code Reviews?

You’re not alone.

Pointing out flaws in someone’s work invites a coding duel at dawn.

But here’s the truth: constructive Code Reviews are at the heart of every successful development team.

The key lies in collaboration.

Code Reviews, when done collaboratively and not nitpicky and ego-driven, can foster an environment of learning and growth, ultimately resulting in happier colleagues who think less frequently about your spontaneous combustion.

The benefits extend far beyond a team. They can improve development processes, produce higher-quality products, and inspire organizational cultural change.

Here are my tips for leaving better Code Reviews with examples.

Understanding the Pull Request

• Start with the Description: Always, always read the description. I know how tempting it is to jump into Files Changed, but you must resist this. Reading the description first clarifies the purpose of the changes and helps you – the reviewer – understand what to focus on.

• Context is Key: I have GitHub’s File Tree on by default. It lets you skim the changed files to get a general sense of the scope of the modifications.

But here’s the catch.

Don’t expect perfect descriptions from the start—especially from junior developers or people not used to creating Pull Requests. Instead of explaining how to put those together, use your PRs as a demonstration.

Don’t tell, show!

Crafting Constructive Comments

• Focus on Collaboration: Frame comments as suggestions for improvement, using phrases like “I noticed…”, “Could we consider…” or “This should be…”. Always leave room for errors and assume you missed something and your suggestion is actually a terrible idea.

• Be Specific: Point to specific lines of code and explain the issue or suggest alternatives.

• Positive Reinforcement: Acknowledge the effort and appreciate the contribution before diving into potential improvements.

I like to use this breakdown when submitting the Code Review:

1. A high-level summary of the PR - does it work as expected, is something missing from the implementation – a good place for a leading indicator of the direction of this PR, such as “This is a great start, …”.

2. Deep-dive comments on specific lines that need to change.

Additional Tips

• Keep it Clear and Concise: if the flaws are apparent, don’t write an epilogue for the review. In the screenshot below, I spotted the thing that doesn’t belong in the PR. I could have written an essay on why we shouldn’t include this dependency here, but it wasn’t necessary. However, I also assumed I didn’t understand the change, so I

• Ask Questions: Don’t be afraid to ask clarifying questions if something in the code is unclear. This can help the author improve the code and teach them great review principles.

These were my tips for increasing your safety at the workplace by leaving nice and constructive Code Reviews.

But just in case, wear a helmet and have a fire extinguisher nearby.

What are your tips for better Code Reviews? Let’s see them 👇

---

📰 Weekly shoutout

1. 5 Ways to Show Your Work Without Being Cocky - Nice collaboration from

   Fran Soto
   and
   Basma Taha
   . Sharing your work has tremendous benefits. There’s nothing worse than dumping energy and time into something that only you know about. I’m a big practitioner of sharing early and often, whether it’s just ideas, pull requests, or this newsletter.

2. Introduction to ACID Properties – there’s no downside to understanding the basics. Sound systems are all built upon basics, and the better you know those basics, the better you’ll understand more complex systems. Great stuff from

   Saurabh Dashora
   .

3. How refactoring almost ruined my marriage - refactors are inviting and

   Anton Zaides
   knows that. They seem like the magic bullet, and we often think: this time, we’ll get it all right. Yep, but no.

---

📣 Share

There’s no easier way to help this newsletter grow than by sharing it with the world. If you liked it, found something helpful, or you know someone who knows someone to whom this could be helpful, share it:

🏆 Subscribe

Actually, there’s one easier thing you can do to grow and help grow: subscribe to this newsletter. I’ll keep putting in the work and distilling what I learn/learned as a software engineer/consultant. Simply sign up here: