Every team’s code review process is a unique little ecosystem. Depending on your project size, team, and culture, your reviews might range from a blunt “Fix your infinite loop, bruh” to a more formal, “This call appears to create a recursive loop when invoked by the x method, which will lead to a stack overflow. This needs to be addressed.”
Regardless of where you fall on that spectrum, intentionally creating a healthy code review culture pays off big time. It’s not just about catching bugs; it’s about how you communicate. Here are a few practices I’ve picked up over the years that help keep reviews constructive and collaborative.
Avoid “You,” Favor “We” or “The Code”
The moment code is pushed and a pull request is created, it’s not “your code” anymore. It’s our code. From that point on, ownership belongs to the whole team. This is a crucial mindset shift because, let’s be honest, putting your work out there for critique is a vulnerable moment. People can get defensive about their code and their style.
We all want to protect the repository and make sure everyone feels responsible for every line of code. By shifting the ownership to the team, we make it a shared goal.
That’s why pointing fingers with “you” or “your” in a code review can feel a bit… pointy. It can come across as accusatory, even when you don’t mean it to be.
Compare these two comments:
- “You did this, but this method is no longer used. You should remove it.”
- “Looks like this method is no longer used, so we can probably remove it to clean things up.”
For some, the difference is trivial. But trust me on this one, I’ve worked with enough developers to know that the “you” language can genuinely sting. It’s a small change that can make a big difference in how feedback is received.
Suggest with Questions
None of us knows everything. As a reviewer, you might have a hunch about something but lack the full context. When that happens, asking a question is your best tool. In the worst-case scenario, you learn something new. In the best case, you spark curiosity and guide the author to a better solution without being demanding.
It’s a classic win-win. But, like all good things (especially coffee), use it in moderation. A PR full of dozens of low-impact questions can stall the progress and lead to a waste of time.
For example, consider these two approaches:
- “The complexity here is O(n2), and it’s possible to get to O(logn). Please fix it.”
- “I see we’re searching the whole array on each iteration here. I’m wondering if we could get a performance boost by using a
HashSetfor quicker lookups?”
The second sentence gently suggests an alternative. And who knows? Maybe a HashSet isn’t feasible for a reason the reviewer hasn’t seen. After all, the author probably has the most context on the “big picture.” A question opens a dialogue instead of shutting it down.
Use “Consider” for Optional Tasks
I know, I know, some people find the word “Consider” a bit passive-aggressive, like a corporate email ninja. But I find it’s a useful tool for suggestions that aren’t strictly necessary show-stoppers. For me, it lives somewhere between a mandatory Task and a simple Comment.
For example: “Consider adding a Javadoc example showing how to use this method.”
The method probably isn’t so complex that people can’t figure it out, but an example would be a nice-to-have. It’s not a blocking issue, but if it gets done, I’ll sleep a little better that night.
(If you’ve got a better word than “Consider,” drop it in the comments. I’m always looking to improve my code review vocabulary!)
Help Out with Code Samples
Sometimes, words are hard. Describing a complex change can be ambiguous and lead to a long back-and-forth. Why not just show what you mean?
Providing a small code snippet in your comment can save a ton of time and mental energy. I’ve been on the receiving end of cryptic comments before, spending way too much time trying to decrypt what a senior dev meant by “re-abstract this inversion.”
Time is precious for everyone, reviewer and author alike. Use all the tools at your disposal. Especially code formatting in comments to make your point as clear as possible. Remember, PRs are historical documents. Treat your comments with the same care you’d treat your code or official documentation.
Develop a Label System
This one isn’t a must-have, and my current team doesn’t use it, but it can be super effective. The default tools you use (like Bitbucket, GitHub, etc.) might not have enough granularity. A “Task” is blocking, but a “Comment” could be anything from a question to a minor suggestion.
You can create your own lightweight system with labels like [NIT], [MINOR], or [STYLE].
- A
[NIT](nitpick) comment is for something you’d prefer but isn’t a big deal. - A
[STYLE]comment might be because the code spacing is making your eye twitch.
By prefixing a comment, you immediately set the author’s expectations about its severity. We don’t use it, but I can definitely see how it would streamline communication.
Don’t Forget to Give Praise!
Code reviews aren’t just about hunting for bugs and suboptimal patterns. As I said before, opening a PR is a vulnerable act. It’s someone putting their effort out there to be judged.
So, don’t forget to celebrate the wins, no matter how small! Acknowledge a clever solution, a well-written test, or a nice refactor. Reinforce the good practices you want to see more of.
A quick “Nice! This is way cleaner” or “Great catch with this edge case!” can make someone’s day and fosters a culture where people aren’t afraid to share their work.
TL;DR
At the end of the day, the language we use in code reviews shapes our team’s culture. The goal isn’t just to ship flawless code; it’s to build a better team and a better codebase together. By being mindful of our words, we can turn a potentially stressful process into a collaborative and educational one.
Here’s the cheat sheet:
- Talk about the code, not the person. Use “we” and “the code” instead of “you” and “your.”
- Ask questions instead of making demands. It opens a dialogue and respects the author’s context.
- Use prefixes for non-blocking feedback.
Consider:or[NIT]are great for suggestions that aren’t mandatory. - Show, don’t just tell. A small code snippet is often clearer than a paragraph of text.
- Give praise! Acknowledge good work to reinforce positive habits and keep morale high.
Mastering the language of code review is a skill, just like writing clean code. And it’s one that pays dividends in team health, code quality, and your own sanity. Happy reviewing!
