Code Review Without the Combat: Building Better Software Together

That time I had just submitted a PR, and a single comment defeated me.

The reviewer wrote: "This variable name is too abstract. I suggest changing it to something with more business semantics."

I stared at that line of code for three seconds. This variable was written by him a month ago, and I had followed his naming style. Why was it abstract now? Even more ironically, after I changed the variable name, he replied again: "I'm not quite sure why it's named this way."

The comment section felt like a silent trial. What started as technical details gradually turned into veiled accusations of "Do you not understand the business?" or "Are your coding habits that bad?"

That day, after merging the PR, I felt deeply frustrated and just wanted to close the IDE and go for a run.

This wasn't an accidental misstep, but a common scenario in our Code Review process: sliding from technical co-construction into mutual nitpicking, and from feedback discussions into defensive postures.

But if we treat Code Review merely as a problem-finding exercise, we easily overlook a fact: the true value of Code Review is not how many issues are pointed out, but how the team grows better together.

To achieve that, beyond technical skills, we need structured process design and the ability to build psychological safety.

1. Why Does Code Review Turn into a Battleground?

Looking back, the tension in our team's PR comments didn't come from technical disagreements, but from a common issue:

Everyone writes code with a defensive mindset and reviews with a fault-finding perspective.

1.1 Defensive Mindset: Writing as if in a Lawsuit

A colleague once said something very honest: "My goal in writing code is not to write well, but to avoid being challenged."

It sounds like a joke, but in teams with high review pressure, it often becomes reality. PRs are written in extreme detail, like lawyer's statements; every step is broken down into tiny pieces for "explainability"; even when there is logical duplication or architectural mess, people dare not modify existing code for fear of being questioned about changing too much.

But the result is counterproductive. The more self-defensive the writing, the more likely it triggers distrust and misreading from reviewers.

1.2 Fault-Finding Perspective: Review Becomes a Contest of Nitpicking

Similarly, reviewers can fall into another trap: instead of helping the other person improve, they are proving "I've thought more thoroughly than you."

You've surely seen comments like these:

"I don't quite understand the point of doing this?"
"Is there a better way to write this?"
"I feel this might be risky."

These comments sound logical, but they lack specific suggestions and a co-construction intent. Over time, Code Review becomes a game of mutual distrust: whoever proposes first takes the lead; whoever is challenged first must defend to the end.

And once technical discussion turns into who is right and who is wrong, it's hard to find room for growth.

2. Psychological Safety First, Then Technical Co-construction

Have you noticed that in teams with a great review atmosphere, interactions often have a sense of "lightness": you can point out problems without embarrassing anyone; you can express different opinions without being labeled; you can admit "I'm not sure" without being seen as unprofessional.

Behind this, it's not because everyone has a good personality, but because they have invisibly built a cultural consensus of psychological safety.

2.1 Use a "Co-construction Tone" Instead of a "Challenge Tone"

Pointing out the same variable name issue with different tones yields vastly different results:

Challenge tone: "This variable name is too abstract. I suggest changing it to xxx."
Co-construction tone: "I'm wondering if this variable could be more aligned with the business, like xxx, to make it easier for others to understand?"

The former triggers defensiveness, while the latter opens the door to discussion.

It's not about being polite to colleagues, but about being more patient in building consensus. The purpose of Code Review is not to find who is wrong, but to write code that is more understandable together.

2.2 Add a Motive Assumption When Questioning

When I guide junior colleagues in reviews, there's a practical trick: if you don't understand why someone wrote something a certain way, first state your assumption, then ask.

For example: "I guess you might have considered scenario A, so you added this handling logic? But I'm thinking, in case of scenario B, it might cause problems. What do you think?"

Or: "Was it for performance reasons that you used this caching strategy? I'm a bit concerned about consistency."

This way, the other person is less likely to feel "you are negating me," and you can also better understand the design motivation behind the code.

In other words, try to understand first, then propose improvements. That is truly mature technical collaboration.

3. Structured Code Review: Making Technical Feedback Systematic

Besides the co-construction mindset, structured processes are also very important.

Many teams do reviews inefficiently because there is no unified sense of process. PRs are written like stream-of-consciousness logs, and reviewers can only shoot from the hip based on experience.

Here is a change I tried, simple but very useful:

3.1 When Writing PR Descriptions, Break Down the Structure in a Few Sentences

① What is the purpose of this change? ② Why do it this way (compared to other approaches)? ③ What are the potential impact points or areas that need attention? ④ How was the change tested (screenshots of tests can also be included)

These sentences seem ordinary, but they greatly reduce communication costs and help reviewers focus accurately on key points, rather than doing a carpet search of every line of code.

3.2 As a Reviewer, Give Suggestions in an Organized Way

I usually organize feedback in this order:

High-priority issues first (e.g., bugs, incorrect logic), without vague phrases like "what do you think";
Suggestions next (e.g., naming, splitting methods);
Global suggestions only need to be mentioned once, don't repeat them line by line;
For harmless issues, add a "nit:" to indicate it's okay not to change.

This approach helps you balance the number of comments and the intensity of tone, and gradually builds a consensus culture of "I'm not nitpicking you, but we are building better code together."

Final Thoughts: Code Review is the Most Underestimated Team Trust Exercise

I think teams that grow fast and have stable technical consensus share a common trait:

They don't do good reviews because they are technically strong;

rather, because they do reviews well, they gradually form a strong technical culture.

Code Review has never been just about finding problems; it is a process of technical people collaborating and recognizing each other.

You feel the other person's understanding from a comment, and you refine your own design expression through repeated explanations.

Technical co-construction starts with review, and trust slowly grows in every act of "writing" and "reading."

Perhaps we have all been anxious, argued, or fallen silent in PR comment sections,

but if you are willing to speak differently and listen from another angle, then Code Review is no longer just about code. It is also the moment when a team truly begins to cooperate.