Code Reviews: The Good, The Bad & The Ugh...

The Bad

I still remember the code review experience that changed everything. A colleague had submitted some problematic code—let’s call it “challenging” at best. As I wrestled with giving constructive feedback, my manager pulled me aside, clearly brimming with their own opinions, and requested my thoughts privately. I did my best to share feedback with empathy and professionalism.

The aftermath, however, was a trainwreck. The next thing I knew, my manager was yelling at them in a glass-walled office! As you might guess, both individuals left the company not long after, each for very different reasons.

This experience has deeply influenced how I try to deliver feedback compassionately, constructively and promptly! A code review can elevate, demoralize, teach, or alienate. But when handled thoughtfully, it builds trust, creates pathways for learning, and strengthens teams. And it starts with how we communicate.

The Ugh

Unfortunately, that wasn't the only time I witnessed a code review go sideways. Over the years, I've seen how these moments shape team culture—for better or worse. Miscommunication, nitpicking, and harsh feedback can instantly derail morale.

Earlier in my career, I prided myself on being thorough, leaving a lethal minefield of comments on PRs, nitpicking this and suggesting alterations there. I realized these weren't helpful after an instructive chat with a senior engineer. Smaller, focused comments on design choices and unclear functionality helped create better code.

The Good

As I grew in my career, I learned that a good code review is so much more than just a checklist for defects. Done right, it becomes a collaborative process—a place where ideas are exchanged, skills are honed, and trust is built.

I remember my first truly great code review experience. Rather than just pointing out improvements, my team lead guided me through a thoughtful discussion. We explored alternatives, examined trade-offs, and arrived at a simpler, more elegant solution.

A meaningful code review focuses on the big picture: logic, architecture, and scalability. It emphasizes mentorship, using questions to open a dialogue instead of directives to shut one down. It celebrates wins, no matter how small, with a simple 'good job' that can resonate deeply. Above all, it’s grounded in empathy, respect, and a shared commitment to building better software together.

Tips for Reviewers

• Use "I" statements. For example, "I think another approach might work well here" is collaborative and open-ended.?
• Focus on the code, not the person. This keeps feedback objective and free from personal biases.
• Asking questions can be more effective than giving directives. It opens up a dialogue and often leads to better solutions.
• Put yourself in the author’s shoes:? I always think about how I'd feel receiving the comments I'm leaving. Maintaining a positive approach and concentrating on growth fosters a culture of understanding and collaboration.

Tips for Authors

• Let me mention the benefits of small PRs: They're easier to understand, boost productivity, and allow for more focused feedback. Microsoft research even supports this idea.
• Write descriptive commit messages that explain both what changed and why. Guide reviewers through your thought process and highlight areas where you want feedback.
• Once you've submitted a pull request, stay engaged. Respond to comments and feedback promptly and be open to suggestions. This speeds up the review process and fosters a collaborative environment where reviewers and authors learn from each other.

Final Thoughts

This article is adapted from a lightning talk I gave last year. I'm writing it now inspired by recent conversations and reading a new research paper on developer "bad days." These moments made me reflect on that talk and want to share my experiences here.

The goal is to write code that's readable and maintainable. Instead of chasing the perfect solution, I look for one that fits well with our goals and the team's overall approach. When it comes to coding, there isn't always a straightforward "right" or "wrong." There are many ways to achieve the same goal, so ensuring that the code you’re reviewing meets that goal effectively is often good enough.

It helps to keep an open mind in code reviews. The more experience we gain, the more we might find ourselves having a preferred way of coding or solving problems. While our experiences are valuable, we should avoid expecting or pushing for code under review to fit our patterns. Instead, our aim should be to help it be its best within its context.

Code reviews don't have to be an old western showdown. They can be collaborative experiences that strengthen teams and improve code quality. While we might encounter 'The Bad' and 'The Ugh' along the way, focusing on empathy, clear communication, and continuous learning helps us create more of 'The Good' moments that strengthen our teams.

Links

Want to dive deeper? Check out Microsoft's study on the Characteristics of Useful Code Reviews—it offers a wealth of insights beyond the benefits of smaller PRs.

Identifying Factors Contributing to “Bad Days” for Software Developers.