Code review comments

English for IT Professionals · Lesson 3 of 5 · B2 Upper intermediate. Give and answer code review feedback that is clear, specific, and friendly.

  • B2 Upper intermediate
  • IT and tech
  • You review a colleague's pull request, or you reply to comments on yours.

By the end of the lesson

  • I can suggest a change as a question, not an order.
  • I can ask why the author chose an approach without sounding critical.
  • I can reply to a comment by agreeing, fixing, or explaining my choice.

Key phrases

The language that does the work

Written comments sound more direct than spoken words, because the reader can't hear your tone. Good reviewers turn orders into questions, explain their reasons, and mark small comments as small. Use these phrases for each job.

Suggesting a change

  • Could we move this into a separate function?
  • What do you think about using a map here?
  • Have you considered caching this result?
  • It might be worth adding a test for the empty case.
  • Nit: there's a typo in the variable name.

Asking why

  • Just curious: why did you choose this library?
  • Is there a reason we're not using the existing helper?
  • Could you explain the reason for this check?
  • I'm not sure I follow this part. Could you walk me through it?

Approving

  • Looks good to me.
  • LGTM, just one small nit.
  • Nice work, approving.
  • Approved, but please fix the typo before you merge.

Replying to comments

  • Good catch, fixed.
  • I went with this approach because it's easier to test.
  • Fair point. I'll change it in a follow-up PR.
  • Done. I've updated the tests too.
  • I see what you mean, but...

Complete the review comments

Tap a gap, then tap the words that fit. Press Check when every gap is full.

1 there's an extra space in the log message.
2 adding an index here? The query looks slow.
3, fixed. I forgot to close the connection.
4 a simple loop because it's easier to read than the reduce version.
5 we're not using the existing date helper?
6. Approving, nice work!

Model dialogue

A pull request review thread

The situation

Sofia, a senior developer in Lisbon, reviews a pull request from Kwame, who joined the team two months ago. They discuss it in comments on the pull request.

Sofia
Nice work on this, Kwame. The new search endpoint is really clean. I left a few comments.
Sofia
Could we move this filter into the database query? Right now we load all the users and filter them in memory, which might be slow for large accounts.
Kwame
Good catch, I didn't think about large accounts. Fixed in the latest commit, and I added a test with ten thousand users.
Sofia
Thanks! Another one: is there a reason you wrote a new date parser instead of using the one in utils?
Kwame
I went with a new one because the utils version doesn't handle time zones. I'm happy to update the shared one instead, if you think that's better.
Sofia
Ah, that makes sense. Updating the shared one sounds better, but it can be a separate pull request. Could you create a ticket for it?
Kwame
Sure, I'll create one and link it here.
Sofia
Nit: the variable name "data2" isn't very clear. Maybe "filteredUsers"?
Kwame
Agreed, renamed.
Sofia
Looks good to me. Approving. Nice work!

Check

What happened?

Read the dialogue, then choose the best answer.

01Why does Sofia suggest moving the filter into the database query?

02Why did Kwame write a new date parser?

03What does "Nit:" tell Kwame?

Common mistakes

Find the mistake

These mistakes make reviews sound rude or unclear, even when the technical point is right. Tap the part of each sentence that is wrong.

Sentence 1

Sentence 2

Sentence 3

Sentence 4

Sentence 5

Practice

Which comment would you write?

Choose

Choose the best answer

Choose the best comment or reply for each situation.

01The best way to suggest a change:

02A reviewer finds a real bug in your code. The best reply:

03You disagree with a suggestion. The best reply:

04A small, optional comment about formatting starts with:

05You don't understand part of the code. You write:

Your turn

Review a pull request

Take a real pull request from your work, or any small piece of code. Write three review comments: one suggestion, one question, and one nit. Then imagine the author's reply to one of them and write that too.

  1. What do you think about ______? It would ______.
  2. Have you considered ______?
  3. Is there a reason ______?
  4. Nit: ______.
  5. Good catch, ______.
  6. I went with ______ because ______.

After the lesson

Keep practicing

In your next real code review, use at least one question instead of an order, and give a reason for every suggestion.

Can you do it now?

Check yourself

  • I can suggest a change as a question, not an order.
  • I can ask why the author chose an approach without sounding critical.
  • I can reply to a comment by agreeing, fixing, or explaining my choice.

Want feedback on your own answers?Practice this with Thomas in a one-on-one lesson. He'll listen, correct what matters, and help you sound like yourself in English.

Book a lesson with Thomas

Spot a mistake on this page? Tell me