Writing · Free lesson
Code-review English: required change or suggestion?
Your teammate sees five review comments and assumes all five block the change. Help them distinguish a required fix from an improvement that can wait.
Professor Scott MendozaThe short answer
State the status explicitly: Required before merge: handle the empty input. Optional: consider a clearer helper name. Polite wording alone does not tell the author whether a change is required.
Separate requirement from politeness.
Could you handle the empty input? can be a polite request for a required fix. Consider renaming this helper can suggest an improvement, but local review conventions still matter. When intent could be unclear, add required before merge or optional. Then explain the specific concern briefly. This helps the author prioritize without guessing from your tone.
Compare the examples
Required before merge: please handle the empty input.
Optional: consider a clearer helper name.
Is this required before merge, or is it an optional suggestion?
Non-blocking usually signals that this comment is not intended to prevent progress under the team’s process. It does not mean the idea is useless, and it does not override other approvals or failed checks.
Build the meaning step by step
Name the review status
Required before merge:
Give the requested action
Please handle the empty input.
Label a separate optional idea
Optional: consider a clearer helper name.
Try it now
Read the reviewer’s intent
Read all answers and explanations
Comment: Optional: consider renaming this helper. Which reading matches the label?
This comment proposes an optional improvement.Optional describes this suggestion. It neither makes the rename mandatory nor removes other checks.
Comment: Required before merge: could you handle the empty input? Is could you evidence that this is optional?
No, the explicit required label controls the intent.Politeness and required status are different. The label states the intended requirement.
A comment says Could we rename this? with no label or shared convention. What reply clarifies its status?
Is this required before merge, or an optional suggestion?Ask about the intended requirement rather than guessing from the question form.
Put it into practice
Separate two review comments
In this review, handling empty input is required before merge. Renaming the helper is optional. Rewrite the combined comment so the author can distinguish them.
Please handle empty input and rename the helper.
See a model answer
Required before merge: handle empty input. Optional: rename the helper for clarity.
Use your team’s actual review process. These labels explain the comment; they do not grant merge permission.
A little more clarity
Common questions
A few useful details before you move on.
Does nit always mean optional?
No universal rule applies across teams. It often marks a small issue, but small and optional are not identical. Ask if the local meaning is unclear.
Is this small cleanup required in this change?
Is a label enough without an explanation?
A label gives status, but a brief reason can still help the author understand the change. Keep the comment about the work rather than the person.
Optional: a clearer name would make the helper’s purpose easier to recognize.
Take it into your day
Say what is required, what is optional and what the comment does not authorize.
English for Careers · Coming Soon
Build clearer software-review conversations.
English for Software Engineers: Career Simulation is coming soon. The planned course develops English for requirements, review, testing and release conversations. Sign up on the course page for its launch news.
Get launch updatesSoftware Engineers · Career Simulation
Your next step · Available on Udemy
Strengthen your English foundations.
The available English Grammar and English Speaking Master Course develops broader grammar, sentence-building and communication foundations. Clear requests and explanations help you communicate review intent.
Explore the course English Master Course: English Grammar and English Speaking