Bring Some Fresh AIR into Your Code Review Comments
In the past few weeks, we talked a lot about code reviews. We discussed about the Four Reasons to Have Code Reviews, the Five Categories of Feedback and Eight Common Pitfalls.
This time, let’s talk about the next step: how to write review comments that don’t get ignored. Comments that spark reflection, not resentment.
I call this the AIR Formula—because the best comments bring some fresh AIR into the process.
The AIR Formula
A = Action — What should be done?
I = Information — Why it matters.
R = Reference — Where to learn more.
That’s it. Simple, but surprisingly powerful.
Let’s walk through each component.
A — Action: Be Clear About What You Want
Most weak review comments fail at the very first step: they don’t tell the author what to do.
Take this example:
void doStuff(const std::unique_ptr<Widget>& iWidgetToUpdate) { // ...}
Comment:
“Why don’t you take it by value?”
That’s not really a request — it’s a riddle. It’s vague, passive-aggressive, and puts the burden on the author to guess your intent.
Instead, make your comment actionable:
“Please take the smart pointer parameter by value instead of a const reference.”
Notice the please. It’s a tiny word, but it softens the tone and keeps the exchange professional, not personal. You’re not giving orders—you’re making a request.
You can also use phrases like:
“Could you consider…”
“Perhaps we could…”
“Would it make sense to…”
They invite collaboration rather than compliance.
I — Information: Explain Why It Matters
Now the comment is actionable — but not useful yet.
If I received that feedback, my first question would be: Why? Why should I take it by value?
Many reviewers stop here and expect others to follow their suggestions without explanation. That’s a missed opportunity for learning — and for trust.
Instead, include a short rationale:
“Please take the smart pointer parameter by value instead of a const reference.
If you pass it by reference, you don’t transfer ownership. If ownership should be shared, pass by value. If not, consider a raw pointer or reference.”
This helps the author understand your reasoning, not just your preference. It builds shared technical context.
R — Reference: Support Your Claim
Even if you’re a recognized expert, don’t expect people to follow your advice blindly.
Add a reference. It shows humility, reinforces credibility, and encourages independent learning.
“Please take the smart pointer parameter by value instead of a const reference.
If you pass by reference, you don’t share ownership…
For more details, see:
• GotW #91 – Smart Pointer Parameters
• C++ Core Guidelines: R.32”
Now your comment is actionable, informative, and verifiable.
That’s AIR.
More AIR Examples
Let’s be honest: most bad review comments aren’t wrong, they’re just… lazy.
We fire them off quickly, assuming the intent is obvious, and move on. But the other person doesn’t live in our head — they see the words as written.
Let’s see how the AIR formula changes that.
❌ “Rename this.”
This one is a classic.
You know exactly why the name is bad, but the author might have no clue what you mean. Are you thinking about naming conventions? Readability? Consistency? Who knows.
✅ Try this instead:
“Hey, could you consider renaming this variable to make it clearer that it represents a configuration object (Action)? I first thought it stored results, so it took me a few seconds to understand what was going on (Information). Our naming convention suggests clarity over brevity—see the Choosing Names section of our style guide (Reference).”
Now it’s clear, polite, and informative. The author understands the reasoning and even has something to check later.
❌ “Don’t use magic numbers.”
We’ve all written this one at some point. But what’s the author supposed to do with that? Replace it with… what exactly?
✅ Try making it concrete:
“Consider replacing
42with a named constant (Action). It’s not clear what this value represents, which could cause maintenance issues later (Information). We recommend symbolic constants for readability—see C++ Core Guidelines ES.45 (Reference).”
❌ “Why did you do it like this?”
This one feels innocent but can easily come across as judgmental — like you’re implying “you did it wrong.”
Let’s make it sound more like genuine curiosity:
✅ Try this instead:
“Could you share why this approach was chosen? (Action) I’m wondering if it’s for readability or maybe there’s a specific constraint I’m not aware of (Information). We try to document non-obvious design choices in code comments—see the Implementation Comments section of our style guide (Reference).”
See the difference? You’re still asking why, but you’re showing openness instead of doubt. That’s a big trust builder.
A Quick Recap
The AIR formula isn’t about being robotic or over-formal.
It’s about being clear, kind, and helpful — three things that make code reviews feel less like inspections and more like conversations.
So next time you’re tempted to type something blunt like “fix this” or “rename that,” pause for a second.
Add a breath of AIR.
You’ll be surprised how much smoother your reviews become.
Should You Always Use AIR?
No.
Not every comment needs all three parts. Sometimes a typo is just a typo. Sometimes you just ask a clarifying question.
But whenever there’s a teaching opportunity — when your comment could help someone learn instead of just change — then use AIR.
Yes, we’re all tired, overwhelmed, sometimes stressed. But slowing down to write a thoughtful comment builds long-term trust and stronger teams. It turns reviews from criticism into mentorship.
Conclusion
Imagine a world where every code review comment brings some fresh AIR:
Clear actions
Honest explanations
Solid references
That world isn’t as far away as it seems. You can start today—one comment at a time.
Your reviews will not only improve the code but elevate the people behind it.