The Human Side of Code Reviews

👥 How to build a Positive Feedback Culture

The PR's been up for three days now. Why hasn't anyone reviewed it?

As a tech leader in a fast-paced scaleup, I’ve heard this frustration more times than I can count. But never was it more prevalent than during the early days of the pandemic when our team, like many others, suddenly found ourselves working remotely.

I remember one particular instance that drove home the importance of effective code review communication. We were working on a high-value feature with multiple dependencies. One of our developers had been heads-down for days, resolving bugs blocking others from using the feature. When he finally finished, he did what we’d always done: he created a pull request, moved the ticket to ‘Ready for Review’, and moved on to his next task.

In our office, this would have been accompanied by a quick turn to a nearby colleague, a tap on the shoulder, and a “Hey, can you take a look at this?” But in our new remote world, it was just a Slack message that got lost in the noise of a busy day.

Days passed. The bug fixes sat unreviewed. Other developers, unable to use the unmerged feature, had moved on to different tasks. Our carefully planned sprint was starting to unravel.

This scenario exposed a critical flaw in our code review process - one that had always existed but had been masked by the ease of in-person communication. We needed to rethink how we approached code reviews in this new, distributed environment.

In this article, we’ll explore some common challenges in code review communication that can derail even the most well-intentioned teams and discuss strategies to overcome them. From my experience leading tech teams through the challenges of remote work and beyond, I’ve learned that effective code reviews are about much more than just examining code - they’re about fostering a culture of collaboration, learning, and continuous improvement.

---

---

🔍 The Challenge of Unclear Review Comments

Picture this: A developer opens their pull request, eager for feedback, only to find comments like “This is a foot gun” or “There’s a cleaner way to do this.” While these comments might be well-intentioned, they leave the developer scratching their head, unsure of what actions to take.

In one instance, I witnessed a junior developer spend hours trying to decipher what a senior developer meant by “This could be more elegant.” The lack of specificity delayed the project and left the junior developer frustrated and unsure of their skills.

Unclear comments can lead to:

1. Wasted time as developers try to interpret vague feedback

2. Inconsistent code quality as a critical issue may be overlooked

3. Missed opportunities for mentorship and knowledge sharing

4. Frustration and decreased morale among team members

To address this issue, we implemented a few key strategies:

Develop a Team Vocabulary

We created a shared language for code reviews to make it clearer when action was needed. For example, here are a few basics.

• “Must” for critical changes required before merging

• “Should” for recommended improvements that could be addressed in future iterations

• “Consider” for suggestions that are open for discussion

Provide Context and Reasoning

We encouraged reviewers to explain the ‘why’ behind their comments. Instead of saying, “This could be cleaner,” we asked them to explain, “This could be more maintainable by using X pattern because...”

Offer Specific Suggestions

We asked reviewers to provide code snippets or links to documentation illustrating their suggested improvements when possible.

Use Tools to Your Advantage

We leveraged our code review tools to create actionable tasks from comments, clarifying what must be addressed before the PR could be merged.

By implementing these strategies, we saw a marked improvement in our code review process. PRs were completed faster, with fewer back-and-forths. Junior developers reported feeling more supported and better understood the reasoning behind suggested changes. Most importantly, our code quality improved as critical issues were identified and addressed.

---

🤔The Trap of Personal Opinions Without Context

We often strive for clean, elegant code. However, this pursuit can sometimes lead to code reviews filled with personal opinions that don’t account for the broader context of the project.

I recall a situation where a senior developer, known for advocating clean code principles, consistently left comments like “This should be refactored for clarity” or “This isn’t adhering to SOLID principles” on pull requests. While his intentions were good, these comments often ignored the realities of our project’s timeline and the complexity of the systems we were working with.

This approach to code reviews can lead to the following:

1. Unnecessary friction between team members

2. Delays in shipping features as developers get caught up in debates about code style

3. Overlooking pragmatic solutions that, while perhaps not textbook-perfect, get the job done efficiently

4. Discouragement of developers who feel their work is constantly being critiqued without consideration for project constraints

To address this issue, we implemented several strategies:

Pre-review demos

We mandated that every feature be demoed to at least two people before going into a code review; this approach allowed for both a demonstration of the functionality and an initial insight into why a developer had used a particular approach. It also served as a heads-up that a code review was about to be requested.

Emphasise Context

We encouraged reviewers to consider the full context of the code they reviewed. Is this a critical path that needs to be optimised? Or is it a rarely-used edge case where readability is more important than performance?

Accept “Alternative” and “Good Enough” Solutions

The opposite of a good idea, can often be another good idea.
R. Buckminster Fuller

“Perfect” isn’t always the enemy of “good.” Sometimes, a solution that works and is understandable is better than a theoretically perfect one that delays shipping.

Use Comments Wisely

We promoted using code comments to explain complex logic or to areas for future refactoring. This allowed us to acknowledge technical debt without blocking progress.

Encourage Dialogue

Instead of leaving prescriptive comments, we asked reviewers to start discussions. “Have you considered X approach? I’m curious about the trade-offs here.”

Respect the Developer’s Expertise

We reminded reviewers that the person who wrote the code should understand the problem deeply. Even if not immediately obvious, their solutions might address constraints that aren’t apparent at first glance.

By shifting our approach, we saw a marked improvement in our code review process and team dynamics. Reviews became more collaborative and less adversarial, we shipped features faster while maintaining code quality, and developers felt more valued and understood.

---

🎯The Issue of Unclear Review Objectives

Code reviews can become a catch-all process without clear objectives. Reviewers might focus solely on code style, overlook functional requirements, or fail to consider the broader impact of the changes. This lack of direction can lead to ineffective reviews that miss critical issues while getting bogged down in minor details.

To address this, we implemented what I like to call the “Iron Triangle of Code Reviews.” This framework ensures that every review addresses three crucial aspects:

Customer Value

Does the code achieve the requirements? Reviewers should verify that the code implements the specified functionality and consider edge cases. The review should also confirm that the changes align with the overall product vision rather than the short-term goal.

Code Quality

Does the code meet our quality criteria? Check adherence to coding conventions and best practices and verify the presence and quality of tests. Assess code resilience and security, performance, and architectural decisions.

Effort Reflection

Is the code fairly reflecting the time spent and the remaining time available? Here, we consider the complexity of the solution in relation to the problem and look for over-engineering or under-development. Given what has been provided, we can assess whether appropriate trade-offs were made given project constraints.

To make this framework effective, we created a code review checklist incorporating these three aspects, trained reviewers on balancing these sometimes competing priorities, and regularly discussed and refined our approach in team retrospectives.

---

📝The Often Overlooked Importance of Descriptive Commit Messages

While we’ve focused largely on the process of code reviews, there’s another critical aspect of code communication that often gets overlooked: commit messages. How often have you seen “updates” as a commit message and wondered, “Updates to what, exactly?”

At Gather, we’ve implemented a structured format for commit messages, significantly improving our ability to track and understand changes.

Here’s the structure we use:

[Web] - feat: PLAT-XXXX, added yellow buttons
^---^ - ^---^ ^------------------^
|         |            |
|         |            +-> Summary in the present tense.
|         +-----> Type: task, docs, feat, fix, style, wip, qa, or test.
|+-------> Package_name: Mono, Api, Web, App, Shared, Server

This structure identifies which part of the system the change affects, categorises its nature, links the commit to a specific task or issue, and briefly describes the change.

By implementing this structured approach to commit messages, we’ve seen several benefits:

1. Easier code reviews: Reviewers can quickly understand the context and purpose of each change.

2. Improved traceability: We can easily track why, when, and where changes were made.

3. Better release management: Compiling release notes and understanding what’s included in each version is simpler.

4. Faster onboarding: New team members can understand the project’s history and evolution more easily.

---

🚀Conclusion

Throughout this article, we’ve explored several common challenges in code review communication:

1. Lack of urgency and context in review requests

2. Unclear or unhelpful review comments

3. Personal opinions without consideration for project realities

4. Unclear objectives for code reviews

5. Vague commit messages

These issues all stem from a common root: ineffective communication. Whether a developer creates a pull request without providing context, a reviewer leaves vague comments, or a team lacks clear review objectives, the result is the same—a suboptimal code review process that can lead to delays, misunderstandings, and missed opportunities for improvement.

The solutions we’ve discussed - from implementing demo sessions and pair programming to creating a shared review vocabulary and using the Iron Triangle framework - all aim to enhance communication and collaboration within the team.

Effective code reviews are not just about catching bugs or enforcing coding standards. They’re an opportunity for knowledge sharing, mentorship, and collective ownership of the codebase. By treating code reviews as a collaborative process rather than a gatekeeping mechanism, we can create a positive feedback culture that benefits individual developers and the team.

As tech leaders, it’s our responsibility to foster this culture. Here are some key takeaways to implement in your teams:

1. Encourage context-sharing: Whether through demos, detailed PR descriptions, or pre-review discussions, ensure that reviewers have the full picture before they start.

2. Promote clear, actionable feedback: Develop a shared review vocabulary and encourage specific, constructive comments.

3. Balance idealism with pragmatism: Remember that perfect code is often the enemy of shipped code. Encourage reviewers to consider the broader context of each change.

4. Set clear review objectives: Use a framework like the Iron Triangle to ensure comprehensive reviews align with team goals.

5. View code reviews as a collaborative process: Encourage discussion and knowledge sharing during reviews rather than treating them as a pass/fail gate.

6. Implement structured commit messages: Encourage clear, descriptive ones to improve traceability and understanding of code changes.

By addressing these common challenges and implementing these strategies, you can transform your code review process from a potential source of frustration into a powerful tool for team growth and product improvement.

Remember, the goal is better code and a better, more collaborative team. So, the next time you’re about to create or review a pull request, take a moment to consider:

How can I make this process more effective, more educational, and more collaborative for everyone involved?

---