Code Review Without the Drama: hedging language for code review comments
About this lesson
Hedging language for code review comments is the focus of this C1 English for IT lesson plan.
- Grammar
- Hedging with might and could, the tentative past (I was wondering whether we need a lock here.) and downtoners, plus the forms after It might be worth and I'd suggest.
- Topic
- Reviewing a pull request at a fictional payments startup, with labels such as nit and blocking and words such as race condition and rubber-stamp.
- Activities
- A pull request thread to read, a review call, self-checking drills, a chat with a blunt reviewer and boxes of comments to rephrase, then review comments to write and feedback to record.
What's inside
Chapter 1Warm-up: Looks Good to Me?
Chapter 2Reading: PR #482
Chapter 3Listening: Can We Hop on a Call?
Chapter 4Grammar: Soft on People, Clear on Code
- Study the scheme: softening feedbackGrammar schemeTry it
- Choose the correct option to complete each commentChoose the optionUnlock
- Fill in the gaps with the correct form of the verbFill in the gapsTry it
- Drag the words into the gaps in the review threadDrag and dropUnlock
- Match each blunt comment with its diplomatic versionMatchUnlock
- Choose the best comment or replyQuizUnlock
Chapter 5Speaking: Say It Without the Drama
Chapter 6Homework: Your Turn to Review
Vocabulary
10 words and phrases from the lesson, each with a picture and audio in edio.
+7 more with pictures and audio in the lessonMore words
- nitpick
- magic number
- follow-up
- bikeshedding
- push back on
- rubber-stamp
- get defensive
Grammar: hedging in code review
Hedging in English turns a verdict into an observation the author can discuss. On a pull request, learners practice six ways to soften a comment, the verb forms after the most common phrases, and labels that show how serious each comment is, so that the tone softens while the status stays clear.
Softening feedback: kind to people, clear about code
Soften how you say it, never whether it blocks the merge.
Six ways to soften a comment
Modals (This could cause a race condition.), the tentative past, a question instead of an order, seem or appear, downtoners such as slightly, and owning your opinion (To me, this reads as two functions in one.) all leave room for the author to answer.
| Tool | Pattern | Example |
|---|---|---|
| Modal verbs | might / could / would + verb | This could cause a race condition. |
| Tentative past | I was wondering whether… / I wanted to check… | I was wondering whether we need a lock here. |
| A question, not an order | Could we…? / Would it make sense to…? | Could we extract this into a helper? |
| seem / appear | seem / appear + to + verb | This seems to duplicate the check above. |
| Downtoners | slightly, a bit, a bit of a + noun, somewhat, not entirely | The new query is slightly slower. |
| Owning your opinion | I'm not sure… / To me, this reads as… | To me, this reads as two functions in one. |
Watch the verb form
It might be worth, Have you considered and Would you mind take -ing; Would it make sense and I wanted take to + verb. I'd suggest takes -ing or a that-clause: I'd suggest renaming it, or I'd suggest that we rename it.
| Phrase | What follows | Example |
|---|---|---|
| It might be worth | -ing | It might be worth adding a test. |
| I'd suggest | -ing, or (that) we / you + base verb | I'd suggest renaming it. / I'd suggest (that) we rename it. |
| Have you considered | -ing | Have you considered using ON CONFLICT? |
| Would you mind | -ing | Would you mind splitting this PR? |
| Would it make sense | to + verb | Would it make sense to move this check? |
| I wanted | to + verb | I wanted to check how this handles a timeout. |
| I was wondering | whether / if + clause | I was wondering whether we need this. |
| Thanks for / Have you thought about | -ing (after a preposition) | Thanks for catching that! |
Labels: nit, suggestion, question, blocking
Many teams start a comment with a label, so everyone sees at once how serious it is. A full comment runs label, softened observation, reason, then a question or suggestion: nit: 86400 is a bit of a magic number, so it's hard to read. Maybe 24 * time.Hour?
Labels many teams put in front of comments
- nit: a tiny detail; fix it or ignore it
- suggestion: an idea the author can take or leave
- question: you need to understand something first
- blocking: must be fixed before the merge
- Not every team uses them, but they are common practice: everyone sees at once how serious a comment is.
A comment that is soft AND clear
labelsoftened observationreasonquestion or suggestion
blocking: This could pay out twice if two retries arrive at once. Could we add a unique constraint?
nit: 86400 is a bit of a magic number, so it's hard to read. Maybe 24 * time.Hour?
Soft tone, clear status
Maybe, if you have a moment at some point, you could possibly look at the retries? is too soft: nobody knows if the merge waits. Soften the wording, never the status. Drop obviously, just and simply as well: they make a fix sound easy and the author feel careless.
Soft tone, clear status
Too soft: does it block the merge?
- Maybe, if you have a moment at some point, you could possibly look at the retries?
Soft and clear
- blocking: I might be missing something, but two retries could both pass this check. Could we fix this before we merge?
Obviously, just, simply
These words make a fix sound easy, so the author feels slow or careless. Instead of “Just use a lock” or “Obviously this needs a test”, try “Could we use a lock here?” or “It might be worth adding a test.”
Taking feedback well
Replies need the same care. To agree: Good catch, thanks! Fixing it now. To disagree without getting defensive, acknowledge the point first: I see your point, but Redis can't share a transaction with Postgres.
You agree
- Good catch, thanks! Fixing it now.
- Fair point, I'll rename it.
- Thanks for flagging this. Fixed in the latest commit.
You disagree, politely
- I see your point, but Redis can't share a transaction with Postgres.
- That's a fair concern. My thinking was that…
- I'm not sure I agree: the helper would hide the retry logic.
Typical mistakes
I'd suggest you to add a test.
I'd suggest adding a test. / I'd suggest (that) you add a test.
suggest + -ing or a that-clause, never suggest somebody to
It might be worth to check the timeout.
It might be worth checking the timeout.
worth + -ing
Would you mind to split this PR?
Would you mind splitting this PR?
mind + -ing
Have you considered to use a lock?
Have you considered using a lock?
consider + -ing
Try the hedging language exercises
Try them yourself: these are the same exercises your students do in edio.
What's in the lesson
- 11 auto-checked exercises
- 3 games
- 2 teacher-checked tasks
- 1 real-life document
- 1 grammar scheme
- 1 set of word cards
- 1 audio clip
- 1 picture
- 1 transcript
The main objectives of this lesson are to:
- write review comments that are soft and clear, with a label for how serious each one is: nit: 86400 is a bit of a magic number.
- hedge with modals, seem and the tentative past: This could cause a race condition. I was wondering whether we need a lock here.
- use the right form after It might be worth, I'd suggest and Would you mind: Would you mind splitting this PR?
- accept feedback or push back on it without getting defensive: Good catch, thanks! I see your point, but…
Lesson 2 of English for IT C1 · Across the Company continues the unit Talking to the team, after async standups in lesson 1. It takes the modals for suggestions of English for IT B1 lesson 11 and the softeners of B2 lesson 16 into written review, with labels and the verb forms after each phrase; the next lesson turns to cleft sentences for listeners outside IT. In a comment thread, nobody hears a tone of voice, so the hedge has to carry it.
A wheel of questions about useful and annoying reviews starts the lesson, then ten words with pictures and audio, from race condition and idempotent to bikeshedding and push back on, and sentence halves to match. Students read the comment thread on PR #482, where one blunt comment sits among labeled, hedged ones, then hear the author and the tech lead settle the open points in an AI-voiced call. Five self-checking drills follow the scheme, among them blunt comments to pair with their tactful versions. In the speaking chapter, students answer the blunt reviewer in a chat, then open boxes that ask them to say a comment without the drama.
Homework starts with the author's replies to the review, with forms to choose, and a memory game of review shorthand such as LGTM, PTAL and IIRC; both check themselves. Students then write four labeled comments on a change of their own, one of them blocking, and record feedback on a colleague's design, two tasks the teacher reviews.
- Grammar:
- hedging and softening · worth / suggest / mind + -ing
- Topic:
- code review · pull requests · feedback
Teaching tips
- Start with the blunt comment: before the reading, let pairs rewrite Obviously you need a unique constraint. Just rewrite it. Then compare their versions with the tech lead's blocking: comment in the thread.
- Grade one problem three ways: pairs write a comment about a missing test that is too blunt, too soft, and soft but clear; the class votes on which one tells the author whether the merge waits.
- With developers, use a pull request the team can share, and have each person label its comments nit, suggestion, question or blocking before rewriting the ones that read as verdicts.
- One-to-one, play a reviewer with no patience: post short, sharp comments on the learner's real code or design, and ask for replies that agree, disagree or suggest a call, all without getting defensive.
Liked it?
Teach the whole lesson in edio
22 exercises in 6 chapters, ready to teach. edio is an online platform for language schools and teachers: ready-made interactive lessons, live classes, homework and student progress in one place.
Start a free trial
7 days, no credit card.
Open the lesson
Find it in the library of 621 ready lessons. Teach it as it is, or copy any chapter into your own lessons.
Teach it live or as homework
Students work in their own accounts, in sync with you during the lesson, and the practice exercises check themselves.
The whole course: English for IT C1 · Across the Company
15 lessons at C1 for people who build software, in American English, with definitions instead of translations. The people of Kestrel Cloud, a fictional payments startup, write updates, reviews, RFCs and postmortems, explain tech to non-tech colleagues and negotiate scope. Real cases include the CrowdStrike outage and the xz backdoor.See the course
Unit 1 Talking to the team
async updates, code review and plain explanations: the future perfect, hedging, cleft sentences
Lesson 1Async Stand-ups: Status Updates People Can Act OnFuture forms for status updates
Lesson 2 · you're hereCode Review Without the DramaHedging in code review
Lesson 3Explaining Tech to Non-Tech PeopleIt-clefts and wh-clefts
Unit 2 Shipping and incidents
estimates, releases and outages: conditionals without if, phrasal verbs, modal perfects
Unit 3 Security and design
advisories, trade-offs and RFCs: passive reporting structures, concession and contrast, nominalization
Unit 4 Docs, metrics and meetings
READMEs, dashboards and follow-ups: participle clauses, describing trends, reporting verbs
Unit 5 Retros, interviews and AI
looking back and ahead: wish and would rather, inversion, formal obligation and permission
