Code review is one of the highest-leverage activities a senior developer or tech lead does. A well-written review comment can teach a junior developer something they’ll carry for years. A poorly written one creates conflict, confusion, or defensiveness — and the issue doesn’t get fixed.

For Vietnamese tech leads working on international teams, code review comments have a specific challenge: written English feedback is more permanent than spoken feedback. A comment stays in the PR for everyone to read. It gets reread. The tone, precision, and intent matter more than in conversation.

Here’s how to write reviews that improve code and build the team.

The Three Levels of Code Review Comments

Before writing anything, it helps to know what level of comment you’re leaving.

Nit (minor, optional):

“Nit: this variable could be named userCount instead of n for clarity.”

The word “nit” signals: I’m flagging this, but don’t block the PR on it. It’s optional cleanup. Using “nit:” explicitly is a signal native to English tech culture — use it freely. It prevents your optional suggestions from feeling like required changes.

Suggestion (useful change, not blocking):

“Consider extracting this into a helper function — it’s used in three places now and will likely be needed again.”

“Consider” and “might want to” signal a suggestion, not a requirement. The reviewer is offering judgment, not mandating a change.

Blocking (must fix before merge):

“This will throw a null pointer exception if user is undefined — we need a null check here before proceeding.”

No hedge language. When something must change, say it directly. Don’t bury a blocking issue in polite language that makes it sound optional.

Writing the Comment Itself

The most common failure in code review comments is leaving a judgment without explaining the reasoning. “This is wrong” is useless. “This will fail when the array is empty because we’re accessing index 0 without checking length” is actionable.

The formula for a useful comment:

  1. What — the specific thing you’re commenting on
  2. Why — the reason it matters (performance, correctness, readability, security)
  3. How — optionally, a suggestion for what to do instead

Weak comment:

“This is inefficient.”

Strong comment:

“This loop runs O(n²) — for each user we’re scanning the full permissions list. With 1,000+ users this will become a bottleneck. Consider building a Set from the permissions list first and doing O(1) lookups instead.”

Notice what the strong comment does:

  • Names the specific line/pattern (the loop)
  • Explains the performance implication with a concrete scale reference (1,000+ users)
  • Offers an alternative approach

The reviewer’s job isn’t just to find problems. It’s to make problems understandable.

Tone Calibration: Softening Without Losing Clarity

English code reviews often use softening language that might feel overly polite to Vietnamese engineers — but in international team culture, these phrases prevent defensiveness without sacrificing the message.

Direct but potentially harsh:

“You’re doing this wrong. Use async/await instead.”

Softened, equally clear:

“This could be simplified with async/await — it would also make the error handling more explicit. Something like: [code example]”

Common softeners that work in code review:

  • “This might…” — “This might cause issues when the request times out.”
  • “Could we…” — “Could we add a test for the edge case where the list is empty?”
  • “I wonder if…” — “I wonder if this should be a constant rather than hardcoded here.”
  • “One thing to consider…” — “One thing to consider: this will break if the timezone offset changes.”
  • “Happy to discuss…” — “Happy to discuss if you had a different reason for this approach.”

These aren’t weakness. They’re precision. “This might cause issues” is different from “this causes issues” — the qualifier is accurate because you haven’t tested every scenario yourself.

Leaving Positive Comments

Many engineers only comment when something is wrong. This is a missed opportunity.

Specific positive comments do real work:

“Nice — using the builder pattern here makes the test much more readable. Good call.”

“Good catch on the race condition in the retry logic — I missed that in my review.”

“This error message is clear and actionable. I’ve seen a lot of vague errors — this is how it should be done.”

Positive feedback tells the developer what to repeat. “Looks good” does nothing. “The way you handled the fallback here is exactly what we want to see in this service” teaches.

Responding to Pushback on Your Comments

Developers push back on code review comments. This is healthy. How you handle it in English matters.

When the pushback is valid:

“Good point — you’re right that the current load doesn’t warrant the optimization. I’ll move this to a tech debt note instead of blocking on it.”

When you still think you’re right but want to discuss:

“I hear you. I still have a concern about the edge case — can we walk through what happens when [specific scenario]? I might be missing something.”

When you’re unsure and want to defer:

“I’m not certain enough about this to block — let’s merge and track it. I’ll open a follow-up issue.”

The goal of code review is better code, not winning an argument. Being willing to say “good point, I’ll update my comment” is one of the most trust-building things a tech lead can do.

🗣️ Key Phrases to Say Out Loud

These are phrases for verbal code review discussions — stand-ups where code is being reviewed live or pair programming sessions.

  1. “This MIGHT cause an ISSUE when [scenario]” /ðɪs maɪt kɔːz ən ˈɪʃuː wɛn/ — Flag a risk without claiming certainty

  2. “Could we ADD a TEST for this CASE?” /kʊd wiː æd ə tɛst fər ðɪs keɪs/ — Request coverage without sounding accusatory

  3. “I WONDER if this SHOULD be a CONstant” /aɪ ˈwʌndər ɪf ðɪs ʃʊd biː ə ˈkɒnstənt/ — Soft suggestion for refactoring

  4. “This is a NIT — don’t BLOCK on it” /ðɪs ɪz ə nɪt doʊnt blɒk ɒn ɪt/ — Signal an optional suggestion explicitly

  5. “Good CATCH — I MISSED that” /ɡʊd kætʃ aɪ mɪst ðæt/ — Specific positive acknowledgment; builds trust

  6. “Happy to disCUSS if you had a DIFferent REAson” /ˈhæpi tə dɪˈskʌs/ — Opens dialogue without conceding

  7. “Let’s MERGE and TRACK it — I’ll open a FOLlow-up” /lɛts mɜːdʒ ænd træk ɪt/ — Pragmatic close when blocking isn’t worth it

📚 Vocabulary

1. Nit /nɪt/

  • Meaning: A minor, optional code review suggestion (from “nitpick”)
  • Example: “Nit: I’d use a more descriptive variable name here, but don’t block on it.”

2. Block /blɒk/ (verb, in PR context)

  • Meaning: To prevent a pull request from being merged until the issue is resolved
  • Example: “I’m blocking this on the missing error handling — it’s a potential data loss bug.”

3. Actionable /ˈækʃənəbəl/ (adjective)

  • Meaning: Specific and clear enough to be acted on immediately
  • Example: “A good code review comment is actionable — it tells you exactly what to change.”

4. Edge case /ɛdʒ keɪs/

  • Meaning: An unusual or extreme scenario that may not be covered by the main logic
  • Example: “This function works for most inputs, but there’s an edge case with empty arrays.”

5. Hardcoded /ˈhɑːrdkoʊdɪd/ (adjective)

  • Meaning: A value written directly into the code rather than coming from a variable or config
  • Example: “The timeout is hardcoded to 30 seconds — we should move it to config.”

6. Track /træk/ (verb, in engineering context)

  • Meaning: To record an issue for later attention (usually by opening a ticket or comment)
  • Example: “Let’s merge this and track the performance concern in a follow-up ticket.”

7. Defer /dɪˈfɜːr/ (verb)

  • Meaning: To postpone addressing something to a later time
  • Example: “We can defer the refactoring — it’s not blocking the feature.”

🎯 Practice Now

Exercise 1: Upgrade the Weak Comments

Rewrite these weak code review comments using the what/why/how formula. Say your versions aloud.

  • “This is bad.”
  • “Wrong approach.”
  • “This needs tests.”
  • “Inefficient.”

Sample rewrites:

  • → “This will fail when the input is null — we don’t have a null check before calling .length. Add a guard clause before this line.”
  • → “Using a mutable global here will cause race conditions in concurrent requests. Consider passing it as a parameter instead.”
  • → “Could we add a test for the case where the list is empty and when it has exactly one item? Those are the boundary conditions most likely to break.”
  • → “This lookup is O(n) inside a loop, so the whole block is O(n²). With large datasets this will be slow — consider a Map for O(1) lookups.”

Exercise 2: Nit vs. Blocking Decision

For each comment below, decide: is this a nit or blocking? Then say the comment aloud using the appropriate language.

  1. A variable is named x instead of userCount
  2. An API endpoint accepts SQL-injectable user input
  3. A test file has no tests for the null case
  4. Comments use British spelling instead of American

Answers:

  1. Nit — “Nit: userCount would be clearer than x here.”
  2. Blocking — “This is a SQL injection risk — we need to sanitize user input before this query.”
  3. Depends on the criticality — likely blocking: “Could we add a null case test? That’s a likely failure point.”
  4. Nit — “Nit: we’re using American English in this codebase — color instead of colour.”

Exercise 3: Verbal Review Walk-Through

Practice this script for a live code review discussion:

“I’ve reviewed the PR — overall it’s solid. A couple of things I wanted to flag. First, there’s one comment I’m blocking on: line 47, the timeout is hardcoded. If we move this to config, we can change it per environment without a deploy. That’s a quick change.

Second, a nit: the function name handleIt isn’t descriptive — processPaymentCallback or similar would make it easier for someone reading this cold. Don’t block on that, just nice-to-have.

One thing I really liked: the error logging on line 83 includes the request ID. That’ll save us a lot of debugging time. Good call.”

Read it aloud 3 times. Time yourself — aim for under 45 seconds at natural pace.

Code reviews are a daily practice that compounds. A tech lead who reviews with precision and teaches rather than just judges will develop stronger engineers around them.

The English is learnable. The mindset — specific, honest, constructive — is what makes the difference.

Export for reading

Comments