Writing Diplomatic Code Review Comments on a Pull Request.
English for Software Engineers and IT Teams. Lesson 8.
Code review is one of the quickest ways to damage trust if your English sounds blunt. In this lesson you step into a GitHub-style pull request at Northbank Digital. The code works, but there are questions about naming, edge cases and a potential performance issue. You need to comment in a way that is clear, respectful and easy to action.
You will read a short PR thread and notice how experienced reviewers separate blocking issues from suggestions, and how they ask questions without sounding accusatory. You will practise softening phrases, giving reasons, and proposing alternatives. You will also practise replying to feedback on your own PR: accepting changes, explaining trade-offs, or negotiating a different solution.
Your artefact is a set of 6–8 review comments plus a short PR description update (intent, scope, testing). The goal is to sound collaborative and precise, even when you disagree.
1. You open the PR and scan the context.
Today you’re stepping into a real pull request at Northbank Digital. The code basically works, but the way you comment matters just as much as the technical point. In English, it’s very easy to sound blunt when you’re trying to be efficient. Our goal is to sound calm, collaborative and precise.
In this first block, we’ll set the scene and make sure you understand what you’re reviewing. You’ll see a PR title, a short description, and a few notes about what changed. You’ll also see a couple of places where a reviewer might have questions: naming, an edge case, and a potential performance issue.
As you read, notice two things. First, what is the author trying to do, in plain English? Second, what information is missing that a reviewer would reasonably ask for? Then you’ll write a short reviewer message that starts positively, asks for missing context, and sets a friendly tone for the rest of the review.
Situation: a PR that works, but needs a careful review.
You’re reviewing a GitHub-style pull request in the Payments service. The author has implemented a change requested by Product: export a CSV of invoices from the admin dashboard. The PR passes tests, but you spot a few risk areas.
A strong code review comment is not a mini-lecture. It’s a clear, respectful request that helps the author take action quickly. At B2 level, your biggest wins are:
Tone first: start with a friendly framing line.
Specificity: point to a file/function/behaviour, not “this is wrong”.
Actionability: ask for a change, a test, or a short explanation.
PR snapshot (what you see on screen).
PR title:Add invoice CSV export endpoint
Author: Maya
Description:
> Adds GET /admin/invoices/export to export invoices as CSV. Used by the Admin UI. Basic tests added.
Scope summary:
New endpoint: /admin/invoices/export
Adds query params: from, to, status
New function: exportInvoicesCsv()
Adds a small unit test for CSV header format
What a reviewer usually needs (but isn’t always written).
Before you comment on details, check whether you have enough context. Typical “missing but important” items:
Intent: Why now? What problem is being solved?
Scope boundaries: What is out of scope (e.g., huge datasets, streaming)?
Testing evidence: What was tested and how? Any manual checks?
Example of a helpful first comment.
> Nice work on this — thanks for pushing it through. Could you add a quick note to the PR description about expected dataset size and how you tested the endpoint (manual steps + any edge cases)? That will make review and future troubleshooting much easier.
In the activity below, you’ll write your own first reviewer message: friendly, specific, and focused on missing context rather than criticism.
Practice & Feedback
Write one short first review comment (about 40–80 words) that you would leave at the top of the PR. You are the reviewer, and Maya is the author.
Keep the situation: a new invoice CSV export endpoint. Your message should:
start positively (a natural, professional tone),
ask for 2–3 specific missing context items (for example: intent/scope/testing), and
avoid sounding accusing or bossy.
Use at least one phrase from the lesson’s style, such as “Nice work on this — …”, “Could you…?”, or “Would it be possible to…?”.
PR details (for reference).
Title: Add invoice CSV export endpoint
Author: Maya
Summary: Adds GET /admin/invoices/export with from, to, status. New exportInvoicesCsv(). Small unit test for CSV header.
Helpful starter phrases.
"Nice work on this — I have a couple of questions."
"Could you add a quick note about…?"
"Would it be possible to include…? That would help reviewers."
2. Listen to a model PR thread and notice the tone.
Now let’s listen to a realistic review thread. You’ll hear Maya, the author, and two reviewers. Notice how experienced reviewers do three key things. First, they separate the technical point from the person, so the comment doesn’t sound like blame. Second, they ask questions to reduce uncertainty, rather than assuming. Third, they label urgency: what is blocking, and what is a minor suggestion.
While you listen, don’t worry about every technical detail. Focus on the language moves: where do reviewers soften a request, how do they justify it with a reason, and how do they invite discussion?
After the audio, you’ll answer a few comprehension questions and pull out exact phrases you can reuse. This is the fastest way to upgrade your own review style: borrow the patterns that already sound natural in professional teams.
Listening task: a short PR conversation.
In the audio at the top of this block, you’ll hear a model thread that feels like GitHub comments. The PR is the same one: invoice CSV export.
As you listen, try to catch examples of these patterns:
Warm opener + question: “Nice work… I have a couple of questions.”
Softened request: “Could we consider…?”, “Would it be possible to…?”
Reason (not just opinion): “That would help avoid…”, “So we don’t…”
Blocking vs suggestion: “Blocking: …” versus “Minor suggestion: …”
What you’re training your ear for.
At B2, the challenge is not grammar. It’s pragmatics: sounding like a colleague.
Compare these two:
Too blunt: “This is inefficient. Fix it.”
Professional: “This looks correct, but I’m slightly concerned about performance on large datasets. Could we consider streaming the response, or at least adding a limit / pagination note in the description?”
Both communicate the same concern, but only the second protects trust.
Tip: capture exact wording, not just the idea.
When you hear a good phrase, write it down exactly. Small words like “slightly”, “might”, “could”, and “in principle” do a lot of work in English.
In the activity, you’ll answer a few questions to prove comprehension and to collect reusable language.
Practice & Feedback
Listen to the PR thread. Then write:
Who says what: name one blocking issue and one minor suggestion mentioned by the reviewers.
Copy two exact phrases from the audio that sound diplomatic (for example a softened question or a polite concern).
In one sentence, explain what Maya (the author) agrees to change.
Keep your answer short but specific. Aim for 70–120 words total. Use complete sentences and include quotation marks around the exact phrases you copied.
3. Turn blunt feedback into diplomatic, actionable comments.
You’ve heard how the reviewers handled it: clear, but not harsh. Now we’ll practise the core micro-skill that makes your code review English sound professional: taking a blunt thought and converting it into a comment that is specific, softened, and easy to act on.
When people sound rude in PRs, it’s often because they skip the steps in the middle. They jump straight from judgement to instruction: “This is bad, change it.” Instead, we’ll use a simple pattern: start with a neutral observation, add a small hedge if needed, give a reason, and then ask a concrete question or propose an alternative.
In a moment you’ll rewrite a set of blunt comments. Keep the technical meaning, but improve the tone. Aim for comments you’d be happy to leave in a public repo with your name on them.
The upgrade pattern: Observation → Concern/Reason → Request.
A diplomatic review comment often follows this shape:
Observation (neutral): “This returns a string…”
Concern + reason (calm): “I’m slightly concerned this could…” / “This might be confusing because…”
Request (actionable): “Could we…?” / “Would it be possible to…?” / “Could you add a test for…?”
This keeps the focus on the code and the next step.
Useful labels: Blocking vs suggestion.
In many teams, clarity matters. Use labels to reduce friction:
Blocking: we shouldn’t merge until it’s addressed.
Suggestion / Minor: good improvement, but not required for merge.
Be careful: if everything is “blocking”, people stop trusting the label.
Blunt vs professional (examples).
Blunt: “This name is wrong.”
Professional: “I think this might be clearer if we rename exportInvoicesCsv to something like buildInvoicesCsv, since it returns a string rather than doing I/O. What do you think?”
Blunt: “You didn’t test edge cases.”
Professional: “Would it be possible to add a test for the case where from is after to? That edge case feels easy to miss.”
Blunt: “This will blow up in production.”
Professional: “This looks correct, but I’m slightly concerned about memory usage if someone exports a large date range. Could we consider streaming, or add an explicit limit and a clear error response?”
Your task in this block.
You’ll rewrite several blunt comments. Keep your rewrites:
short (1–3 sentences each),
specific (mention the exact item), and
collaborative (invite a response when appropriate).
Try to use at least three chunk-bank phrases across your rewrites.
Practice & Feedback
Rewrite the four blunt review comments below into diplomatic, actionable GitHub comments.
Write 4 separate comments, each 25–55 words.
Rules:
Keep the same technical meaning.
Use at least three of these phrases across the set: “Could we consider…?”, “I’m not sure this handles…”, “This looks correct, but I’m slightly concerned about…”, “Would it be possible to add a test for…?”, “What was the reasoning behind…?”.
Include one comment labelled Blocking: and one labelled Minor suggestion:.
Make them sound like you’re talking to a respected colleague (Maya).
Blunt comments to rewrite.
"Why are you loading everything into memory? That’s bad."
"This function name is misleading."
"No test for invalid dates."
"You didn’t explain how you tested this."
PR context (so your comments are specific).
Endpoint: GET /admin/invoices/export
Function: exportInvoicesCsv() returns a CSV string
Missing edge case: from after to
Performance worry: large date range could create a big CSV
4. Reply to feedback on your own PR in a chat thread.
So far you’ve been the reviewer. Now let’s switch roles: you are the author, and you’re receiving feedback in a PR thread. This is where tone can go wrong in the other direction. Some people become defensive: “That’s not necessary.” Others accept everything, even when the request is too big for the current scope.
A professional PR author reply has three parts: acknowledge the comment, state what you’ll do next, and, if needed, negotiate scope with a reason and an alternative plan. You can disagree politely, but you must stay concrete.
In the task, you’ll do a short chat-style simulation. You’ll receive three reviewer comments. You’ll reply as Maya. Some replies should be straightforward acceptance, and one should be a polite negotiation: you agree in principle, but propose a smaller change now and a follow-up later. That’s a very common engineering move, and you can do it in calm, natural English.
Author replies: accept, explain, or negotiate.
In a PR conversation, your replies create a public record of how you work. The goal is to be easy to collaborate with.
A solid author reply often uses this structure:
Acknowledge: “Good point — …” / “Thanks, that makes sense.”
Commit (or clarify): “I’ll update it.” / “I’ll add a test for…” / “Just to check: do you mean…?”
If needed, negotiate scope (calmly):
“I agree in principle, but…”
“Given the timeline, I’d prefer to…”
“Happy to follow up with…”
Examples you can reuse.
Accepting a change
> Good point — I’ll update the function name and push a commit shortly.
Asking a clarification question
> Just to check I’ve understood: do you want the endpoint to reject large date ranges with a 400, or return a partial result?
Negotiating a different solution
> I agree in principle, but I’d prefer to add a limit in this PR and follow up with streaming next sprint. That reduces risk now and keeps the change set manageable.
What to avoid.
“That’s wrong.” (sounds personal)
“We don’t need that.” (sounds dismissive)
“It’s fine.” (sounds vague and risky)
Your chat simulation.
You’ll reply to three reviewer messages. Keep each reply short (2–4 lines), but make sure every reply contains a clear next step.
Practice & Feedback
Chat simulation: reply as Maya (author) in the PR thread.
You will see three reviewer comments in the resource section. Write three separate replies, labelled Reply 1, Reply 2, Reply 3.
Aim for 35–70 words per reply. In at least one reply, politely negotiate scope using “I agree in principle, but…” and propose a follow-up plan.
Keep the tone collaborative and specific: say what you will change (rename, add a test, update description, add a limit/streaming plan). End one reply with an invitation like “Happy to discuss quickly if that helps.”
Reviewer comments you need to reply to.
Alex: "Minor suggestion: could we rename exportInvoicesCsv()? It reads like it does I/O, but it returns a string."
Sam: "Blocking: I don’t think we should merge until we handle large exports. Streaming would be ideal."
Sam: "Would it be possible to add a test for the case where from is after to?"
5. Write your set of review comments for the key issues.
Now we’ll move from individual sentence practice to a more realistic review output: a set of comments that cover the main issues in the PR. This is where you show professional judgement. You don’t need to comment on every line of code, but you do need to cover the risks that matter: performance for large exports, a clear edge case, naming clarity, and evidence of testing.
As you write, think like a teammate who wants to merge safely. Your comments should be easy for Maya to action. That means each comment should include the ‘what’ and the ‘why’, plus a concrete next step.
You’ll write 6 to 8 comments, mixing blocking items and minor suggestions. Use labels sparingly and correctly. Also vary your language so it doesn’t sound robotic: include questions, suggestions, and one invitation to discuss if it’s complex.
When you’re done, you’ll have a reusable template style you can apply to any PR you review this week.
Building a full review: coverage without overload.
A strong PR review is a small, structured set of comments that:
catches meaningful risk,
removes ambiguity,
keeps tone respectful,
and helps the author land the change.
You are not trying to prove you’re clever. You’re trying to make the codebase safer.
The review checklist for this PR.
For the invoice CSV export, your review should typically cover:
1) Performance / memory
If the PR builds a full CSV in memory, the risk is large exports. You can:
request streaming, or
request a limit + error handling + documentation.
2) Edge cases and validation
Date range logic is a classic source of bugs. A good reviewer asks:
What happens if from > to?
What happens if params are missing?
3) Naming and readability
Names are not cosmetic. They prevent misuse.
4) Testing evidence
You don’t need a huge test suite, but you need confidence. Ask for:
one or two additional tests,
and a short “how I tested” note.
Language bank (mix and match).
Here are patterns that sound natural in professional English:
“Nice work on this — I have a couple of questions.”
“What was the reasoning behind…?”
“This looks correct, but I’m slightly concerned about…”
“I’m not sure this handles the case where…”
“Would it be possible to add a test for…?”
“Minor suggestion: …”
“Blocking: I don’t think we should merge until…”
“Happy to discuss quickly if that helps.”
Aim for balance.
If you mark something as Blocking, make sure it’s genuinely merge-risk. If it’s more about style, keep it as a suggestion.
In the activity, you’ll write a full set of 6–8 comments. This is your main artefact for the lesson.
Practice & Feedback
Write 6–8 GitHub review comments for Maya’s PR. Each comment should be 20–50 words.
Requirements:
Include at least 2 comments that are questions (not instructions).
Include 1–2 comments labelled Blocking: (merge-risk items only).
Include 2–3 comments labelled Minor suggestion:.
Cover all four areas: performance/memory, edge case validation, naming/readability, and testing evidence.
Use at least 5 phrases from the language bank in this lesson (you can adapt them).
Write them as if you are commenting in the PR: short, specific, and respectful.
PR context for your review comments.
Endpoint: GET /admin/invoices/export
Query params: from, to, status
Implementation: builds CSV as a string in memory and returns it
Existing test: checks CSV header format only
Known missing edge case: from is after to
Naming: function is called exportInvoicesCsv() but returns a string
Your goal as reviewer.
Help Maya merge safely, with clear scope and confidence.
6. Capstone: update the PR description and close the thread.
You’ve now practised both sides of the review: writing comments and replying as an author. To finish, we’ll produce the second part of the lesson artefact: a short PR description update. This is a surprisingly high-impact habit. A good description reduces back-and-forth, speeds up review, and makes future debugging easier.
In many teams, the PR description is also a stakeholder-safe summary: it explains intent, scope, and how the change was tested, without going into internal drama. You’ll write a compact update for Maya’s PR, then you’ll post a final comment that summarises what changed and what remains as follow-up.
Think of this as closing the loop professionally. You’re not just saying “done”. You’re making it easy for reviewers to approve and for the team to understand the decision. Use time-friendly wording, and if you’ve negotiated scope, capture it clearly.
What a strong PR description update looks like.
After review comments, a great author does two things:
Updates the PR description so reviewers don’t have to hunt through the thread.
Posts a short summary comment to close the loop.
This is especially important when you decide on a trade-off, like “limit now, streaming later”.
Template: PR description update (copyable).
Use headings so it’s scannable:
Intent: why this change exists.
Scope: what’s included and what’s explicitly out of scope.
Testing: what you tested (unit tests + manual steps).
Notes / Follow-ups: what will be done later.
Model example (adapt for this PR).
Intent
Add a CSV export endpoint for admin invoice reporting.
Scope
Adds GET /admin/invoices/export with from, to, status.
Includes validation for invalid date ranges.
Adds an export size limit to prevent large in-memory responses.
Out of scope
Streaming CSV responses (follow-up ticket next sprint).
Testing
Unit tests: CSV header + invalid date range.
Manual: called endpoint with a small date range and verified file opens correctly in Excel/Sheets.
Follow-ups
Add streaming response support.
Mini rubric for your final output.
Your update is successful if it is:
Clear: intent, scope, and testing are obvious.
Safe: mentions the limit or mitigation for large exports.
Professional: calm tone, no blame.
Actionable: follow-up is explicit.
Now you’ll write both the updated description and a final summary comment to the reviewers.
Practice & Feedback
Write two items:
A) PR description update (about 120–180 words) using headings like Intent / Scope / Testing / Follow-ups. Include the decision about handling large exports (limit now, streaming later) and the edge case validation.
B) Final thread comment (about 40–80 words) addressed to the reviewers. It should summarise what you changed and invite another look.
Keep the tone calm and collaborative. Use at least two phrases from the chunk bank, such as “Good point — I’ll update it.”, “I agree in principle, but I’d prefer to…”, or “Happy to discuss quickly if that helps.”
Facts to include (choose realistic details).
Endpoint: GET /admin/invoices/export
Added/changed after review: rename function, add invalid date range test, add limit and error handling, update description
Follow-up: streaming response next sprint
Useful phrases.
"Good point — I’ll update it."
"I agree in principle, but I’d prefer to…"
"Would it be possible to…?" (only if you ask for final confirmation)
