eduKate Singapore

VIEW THIS AS

Auto mode follows the Route Engine until you choose a viewpoint.

YOU ARE HERE

ROUTE CHECK

CONNECTED TO

WHAT NEXT

Use the canonical route for this room, or HELP if you are unsure.

Next useful routeCanonical hubHELP

Why English? | Writing Code Review Comments Through Context, Evidence, Severity, Suggestions and Respectful Collaboration

—

by

eduKate Asia
Three secondary students review open books and notes together in a classroom.

WHY ENGLISH? · PRACTICAL READING

Turn a code review comment into a precise, kind and testable contribution to better software

Code review comments are short pieces of workplace writing with unusually large consequences. A few words can reveal a defect, improve maintainability, teach a pattern, block an unsafe change or accidentally create conflict. English matters because the reviewer must connect a specific change to evidence, explain its severity and invite the smallest useful next action.

People searching how to write code review comments, pull request feedback, code review best practices or respectful developer feedback need more than polite phrases. They need a method that distinguishes a blocking defect from a suggestion, a question from a claim and a personal preference from a documented standard.

GitHub documents comments, suggestions, approvals and requests for changes as distinct review actions. Google’s published engineering practices add a human principle: discuss the code rather than judging the developer, explain reasoning and balance clear direction with room for the author to solve the problem.

ROUTE 1Understand the change
understand the change and review scopeROUTE 2Write the comment
write evidence-led comments with clear severityROUTE 3Collaborate and resolve
collaborate, resolve and preserve decisionsROUTE 4Transfer the skill
transfer review language into study and work

Open the complete chapter index · Visit the English Learning Hub

Complete guide index

Start with the pull request’s purpose and evidence, place each comment at the right scope, state impact and severity, propose or request a testable next step, then close the loop without turning code review into a contest.

Understand the change
  1. Read the purpose before the diff
  2. Choose the right comment scope
  3. Separate observation from interpretation
  4. Review the whole change, not only syntax
Write the comment
  1. Lead with the concrete concern
  2. Explain reasoning and cite standards
  3. Label severity honestly
  4. Offer a testable next step
  5. Use examples without taking over
Collaborate and resolve
  1. Keep the comment about code, not identity
  2. Respond to disagreement with evidence
  3. Verify before resolving a thread
  4. Record deferred work outside the thread
Transfer the skill
  1. Turn review language into a reusable learning habit

CHAPTER 1 OF 14 · Understand the change

1. Read the purpose before the diff

Back to contents

A correct line can be wrong for the task

The pull request description, linked issue, acceptance criteria and surrounding architecture establish what the change is meant to accomplish.

Write a one-sentence purpose statement before leaving comments and test every concern against it. This is where English becomes operational: the reader must keep the label, number, date, unit and source together instead of remembering only the most striking figure.

Practical example. A reviewer sees a neat validation function but notices that the project brief requires offline behaviour the new dependency cannot support.

Use a source–meaning–action check

First copy the source wording exactly. Next explain what it means in this specific document. Then write the action, owner and deadline that follow. If any link is missing, pause and ask a precise question before paying, enrolling, travelling or submitting.

  • Read summary.
  • Open linked issue.
  • Name user outcome.
  • List constraints.
Did You Know? GitHub’s review quickstart begins by reading the summary and relevant discussion before the changed files.
Important limit. A description can be incomplete; ask rather than inventing intent.

How this skill transfers

Purpose-first reading supports essays, experiments and project work. The same discipline supports examinations, further study and careers because students learn to distinguish a heading from evidence, an estimate from a final amount, a status from an outcome and general guidance from a personal decision.

Parents and mentors can help by asking the learner to show the exact line that supports each conclusion. They should not take over the account, application or decision. A strong final note uses two sentences: “The source confirms …” and “The source does not yet confirm …”.

CHAPTER 2 OF 14 · Understand the change

2. Choose the right comment scope

Back to contents

Location changes meaning

A line comment suits a local expression, a file comment suits an entire file and a summary comment suits cross-cutting design or release risk.

Place the feedback where the author can connect it to the smallest relevant unit without scattering one issue across many threads. This is where English becomes operational: the reader must keep the label, number, date, unit and source together instead of remembering only the most striking figure.

Practical example. A repeated error-handling pattern receives one summary comment with two examples rather than twelve identical line comments.

Use a source–meaning–action check

First copy the source wording exactly. Next explain what it means in this specific document. Then write the action, owner and deadline that follow. If any link is missing, pause and ask a precise question before paying, enrolling, travelling or submitting.

  • Pick line scope.
  • Pick file scope.
  • Pick review summary.
  • Avoid duplicate threads.
Did You Know? GitHub provides comments on lines, files and the pull request conversation because review concerns have different scopes.
Important limit. A local comment should not pretend to settle a system-wide design decision.

How this skill transfers

Scope control supports annotations and research notes. The same discipline supports examinations, further study and careers because students learn to distinguish a heading from evidence, an estimate from a final amount, a status from an outcome and general guidance from a personal decision.

Parents and mentors can help by asking the learner to show the exact line that supports each conclusion. They should not take over the account, application or decision. A strong final note uses two sentences: “The source confirms …” and “The source does not yet confirm …”.

CHAPTER 3 OF 14 · Understand the change

3. Separate observation from interpretation

Back to contents

Evidence comes before conclusion

The reviewer should distinguish what the code does from what they infer it may cause.

State the visible fact, then the condition and expected consequence; use a question when the inference depends on missing context. This is where English becomes operational: the reader must keep the label, number, date, unit and source together instead of remembering only the most striking figure.

Practical example. “This branch returns before the audit write; could failed requests therefore be absent from the log?” is clearer than “Logging is broken.”

Use a source–meaning–action check

First copy the source wording exactly. Next explain what it means in this specific document. Then write the action, owner and deadline that follow. If any link is missing, pause and ask a precise question before paying, enrolling, travelling or submitting.

  • Quote behaviour.
  • Name condition.
  • State inference.
  • Invite correction.
Did You Know? A well-formed question can expose a defect without overstating certainty.
Important limit. Questions should not disguise an accusation whose answer the reviewer has already assumed.

How this skill transfers

Observation discipline supports science and source analysis. The same discipline supports examinations, further study and careers because students learn to distinguish a heading from evidence, an estimate from a final amount, a status from an outcome and general guidance from a personal decision.

Parents and mentors can help by asking the learner to show the exact line that supports each conclusion. They should not take over the account, application or decision. A strong final note uses two sentences: “The source confirms …” and “The source does not yet confirm …”.

CHAPTER 4 OF 14 · Understand the change

4. Review the whole change, not only syntax

Back to contents

Quality has several dimensions

Design, functionality, complexity, tests, naming, comments, style and documentation can all matter.

Use a small checklist matched to the repository instead of focusing only on the language feature you notice fastest. This is where English becomes operational: the reader must keep the label, number, date, unit and source together instead of remembering only the most striking figure.

Practical example. A patch compiles, but its public API name, failure test and migration note are still missing.

Use a source–meaning–action check

First copy the source wording exactly. Next explain what it means in this specific document. Then write the action, owner and deadline that follow. If any link is missing, pause and ask a precise question before paying, enrolling, travelling or submitting.

  • Check design.
  • Check behaviour.
  • Check tests.
  • Check maintainability.
Did You Know? Google’s reviewer guide explicitly covers more than style and formatting.
Important limit. A checklist does not replace judgment or specialist review.

How this skill transfers

Multi-criteria reading supports rubrics and admissions decisions. The same discipline supports examinations, further study and careers because students learn to distinguish a heading from evidence, an estimate from a final amount, a status from an outcome and general guidance from a personal decision.

Parents and mentors can help by asking the learner to show the exact line that supports each conclusion. They should not take over the account, application or decision. A strong final note uses two sentences: “The source confirms …” and “The source does not yet confirm …”.

CHAPTER 5 OF 14 · Write the comment

5. Lead with the concrete concern

Back to contents

Readers need an anchor

Begin with the affected behaviour, requirement or risk rather than a generic emotion or verdict.

Use the pattern context–observation–impact so the author can test the statement. This is where English becomes operational: the reader must keep the label, number, date, unit and source together instead of remembering only the most striking figure.

Practical example. “When the token is expired, this path retries indefinitely, which can hold a worker” gives the author a precise starting point.

Use a source–meaning–action check

First copy the source wording exactly. Next explain what it means in this specific document. Then write the action, owner and deadline that follow. If any link is missing, pause and ask a precise question before paying, enrolling, travelling or submitting.

  • Name context.
  • Describe behaviour.
  • State impact.
  • Avoid personal labels.
Did You Know? Technical directness and interpersonal kindness are compatible.
Important limit. Do not bury a serious issue under so much cushioning that severity becomes unclear.

How this skill transfers

Clear openings support reports and examination answers. The same discipline supports examinations, further study and careers because students learn to distinguish a heading from evidence, an estimate from a final amount, a status from an outcome and general guidance from a personal decision.

Parents and mentors can help by asking the learner to show the exact line that supports each conclusion. They should not take over the account, application or decision. A strong final note uses two sentences: “The source confirms …” and “The source does not yet confirm …”.

CHAPTER 6 OF 14 · Write the comment

6. Explain reasoning and cite standards

Back to contents

Because turns preference into review

A request is easier to evaluate when it links to a requirement, invariant, style guide, test or observable user effect.

Give the shortest sufficient reason and link the controlling source when one exists. This is where English becomes operational: the reader must keep the label, number, date, unit and source together instead of remembering only the most striking figure.

Practical example. The reviewer links the repository rule for timezone-aware timestamps instead of saying, “We never do it this way.”

Use a source–meaning–action check

First copy the source wording exactly. Next explain what it means in this specific document. Then write the action, owner and deadline that follow. If any link is missing, pause and ask a precise question before paying, enrolling, travelling or submitting.

  • State rule.
  • Link source.
  • Explain consequence.
  • Allow better solution.
Did You Know? Google’s guidance recommends explaining intent or the code-health reason behind a comment.
Important limit. A link is evidence only when it actually applies to this repository and case.

How this skill transfers

Reason-giving supports persuasive writing. The same discipline supports examinations, further study and careers because students learn to distinguish a heading from evidence, an estimate from a final amount, a status from an outcome and general guidance from a personal decision.

Parents and mentors can help by asking the learner to show the exact line that supports each conclusion. They should not take over the account, application or decision. A strong final note uses two sentences: “The source confirms …” and “The source does not yet confirm …”.

CHAPTER 7 OF 14 · Write the comment

7. Label severity honestly

Back to contents

Priority is part of meaning

A correctness blocker, security concern, suggestion, question and nit should not sound identical.

Use the team’s conventions and state whether approval depends on the change. This is where English becomes operational: the reader must keep the label, number, date, unit and source together instead of remembering only the most striking figure.

Practical example. A reviewer writes “Blocking: this bypasses authorisation for archived records” and “Suggestion: rename this helper for readability.”

Use a source–meaning–action check

First copy the source wording exactly. Next explain what it means in this specific document. Then write the action, owner and deadline that follow. If any link is missing, pause and ask a precise question before paying, enrolling, travelling or submitting.

  • Name level.
  • State impact.
  • State approval effect.
  • Keep labels consistent.
Did You Know? Google’s guide uses “Nit:” for optional polish, which helps authors allocate attention.
Important limit. Severity labels are not a substitute for evidence.

How this skill transfers

Priority language supports incident response and study planning. The same discipline supports examinations, further study and careers because students learn to distinguish a heading from evidence, an estimate from a final amount, a status from an outcome and general guidance from a personal decision.

Parents and mentors can help by asking the learner to show the exact line that supports each conclusion. They should not take over the account, application or decision. A strong final note uses two sentences: “The source confirms …” and “The source does not yet confirm …”.

CHAPTER 8 OF 14 · Write the comment

8. Offer a testable next step

Back to contents

Action completes the feedback

The author should know what outcome would resolve the concern even if the exact implementation remains theirs.

Ask for a behaviour, test, documentation change or explanation that can be verified. This is where English becomes operational: the reader must keep the label, number, date, unit and source together instead of remembering only the most striking figure.

Practical example. “Please add a test showing two simultaneous updates cannot lose an item” leaves implementation open but defines evidence.

Use a source–meaning–action check

First copy the source wording exactly. Next explain what it means in this specific document. Then write the action, owner and deadline that follow. If any link is missing, pause and ask a precise question before paying, enrolling, travelling or submitting.

  • Name desired outcome.
  • Suggest test.
  • Avoid over-prescription.
  • Invite alternatives.
Did You Know? The author may know a better implementation than the reviewer while still needing the same verified outcome.
Important limit. Do not paste a large replacement without understanding ownership and design context.

How this skill transfers

Outcome writing supports project briefs. The same discipline supports examinations, further study and careers because students learn to distinguish a heading from evidence, an estimate from a final amount, a status from an outcome and general guidance from a personal decision.

Parents and mentors can help by asking the learner to show the exact line that supports each conclusion. They should not take over the account, application or decision. A strong final note uses two sentences: “The source confirms …” and “The source does not yet confirm …”.

CHAPTER 9 OF 14 · Write the comment

9. Use examples without taking over

Back to contents

Illustration is not command

A small code suggestion can clarify syntax, while a larger design issue often needs discussion rather than a pasted rewrite.

Mark examples as examples and distinguish required behaviour from optional implementation. This is where English becomes operational: the reader must keep the label, number, date, unit and source together instead of remembering only the most striking figure.

Practical example. The reviewer shows a three-line guard clause but says an equivalent early validation is acceptable.

Use a source–meaning–action check

First copy the source wording exactly. Next explain what it means in this specific document. Then write the action, owner and deadline that follow. If any link is missing, pause and ask a precise question before paying, enrolling, travelling or submitting.

  • Show minimal example.
  • Label suggestion.
  • Preserve author agency.
  • Avoid unrelated refactor.
Did You Know? GitHub supports suggested changes that authors can apply directly, but the reviewer still must explain why.
Important limit. A syntactically valid suggestion can still be architecturally wrong.

How this skill transfers

Examples support teaching when their limits are explicit. The same discipline supports examinations, further study and careers because students learn to distinguish a heading from evidence, an estimate from a final amount, a status from an outcome and general guidance from a personal decision.

Parents and mentors can help by asking the learner to show the exact line that supports each conclusion. They should not take over the account, application or decision. A strong final note uses two sentences: “The source confirms …” and “The source does not yet confirm …”.

CHAPTER 10 OF 14 · Collaborate and resolve

10. Keep the comment about code, not identity

Back to contents

Respect improves signal

Personal judgments trigger defensiveness and add no reproducible technical evidence.

Use nouns such as branch, interface, query and test; avoid claims about intelligence, care or motives. This is where English becomes operational: the reader must keep the label, number, date, unit and source together instead of remembering only the most striking figure.

Practical example. “This name hides the unit” replaces “You chose a confusing name.”

Use a source–meaning–action check

First copy the source wording exactly. Next explain what it means in this specific document. Then write the action, owner and deadline that follow. If any link is missing, pause and ask a precise question before paying, enrolling, travelling or submitting.

  • Name artefact.
  • Describe effect.
  • Remove motive.
  • Keep dignity.
Did You Know? Google’s public guidance explicitly recommends commenting on the code rather than the developer.
Important limit. Respectful language does not require accepting unsafe code.

How this skill transfers

Person–work separation supports peer review. The same discipline supports examinations, further study and careers because students learn to distinguish a heading from evidence, an estimate from a final amount, a status from an outcome and general guidance from a personal decision.

Parents and mentors can help by asking the learner to show the exact line that supports each conclusion. They should not take over the account, application or decision. A strong final note uses two sentences: “The source confirms …” and “The source does not yet confirm …”.

CHAPTER 11 OF 14 · Collaborate and resolve

11. Respond to disagreement with evidence

Back to contents

Pushback can reveal context

A developer may know constraints the reviewer missed, or the review may reveal an unrecorded design decision.

Restate the shared goal, compare evidence and escalate to synchronous discussion when written exchange stops progressing. This is where English becomes operational: the reader must keep the label, number, date, unit and source together instead of remembering only the most striking figure.

Practical example. A performance concern is resolved when the author shares benchmark data and the team records the acceptable threshold.

Use a source–meaning–action check

First copy the source wording exactly. Next explain what it means in this specific document. Then write the action, owner and deadline that follow. If any link is missing, pause and ask a precise question before paying, enrolling, travelling or submitting.

  • Acknowledge context.
  • Restate outcome.
  • Compare evidence.
  • Record decision.
Did You Know? Google recommends moving difficult consensus conversations to a call or meeting and recording the result in the review.
Important limit. Authority should not replace technical reasoning when evidence can decide.

How this skill transfers

Disagreement skills support seminars and workplaces. The same discipline supports examinations, further study and careers because students learn to distinguish a heading from evidence, an estimate from a final amount, a status from an outcome and general guidance from a personal decision.

Parents and mentors can help by asking the learner to show the exact line that supports each conclusion. They should not take over the account, application or decision. A strong final note uses two sentences: “The source confirms …” and “The source does not yet confirm …”.

CHAPTER 12 OF 14 · Collaborate and resolve

12. Verify before resolving a thread

Back to contents

Change is not proof

A reply such as “fixed” should lead to inspection of the new diff, test or documentation.

Re-open the affected context and check whether the change solves the original concern without introducing another. This is where English becomes operational: the reader must keep the label, number, date, unit and source together instead of remembering only the most striking figure.

Practical example. The retry limit is added, but the reviewer notices the error still lacks the request identifier required for diagnosis.

Use a source–meaning–action check

First copy the source wording exactly. Next explain what it means in this specific document. Then write the action, owner and deadline that follow. If any link is missing, pause and ask a precise question before paying, enrolling, travelling or submitting.

  • Read new diff.
  • Check test.
  • Check side effects.
  • Then resolve.
Did You Know? A resolved interface state records workflow, not infallibility.
Important limit. Do not prolong a thread after the agreed evidence is satisfied.

How this skill transfers

Verification supports marking and quality assurance. The same discipline supports examinations, further study and careers because students learn to distinguish a heading from evidence, an estimate from a final amount, a status from an outcome and general guidance from a personal decision.

Parents and mentors can help by asking the learner to show the exact line that supports each conclusion. They should not take over the account, application or decision. A strong final note uses two sentences: “The source confirms …” and “The source does not yet confirm …”.

CHAPTER 13 OF 14 · Collaborate and resolve

13. Record deferred work outside the thread

Back to contents

Not-now needs an owner

Valid feedback may be out of scope for the current change, but disappearance is not a plan.

Create the team’s normal issue or task with scope, rationale and owner, then link it from the review. This is where English becomes operational: the reader must keep the label, number, date, unit and source together instead of remembering only the most striking figure.

Practical example. A broader database migration is deferred to a tracked issue while the current patch adds the safe compatibility check.

Use a source–meaning–action check

First copy the source wording exactly. Next explain what it means in this specific document. Then write the action, owner and deadline that follow. If any link is missing, pause and ask a precise question before paying, enrolling, travelling or submitting.

  • Define follow-up.
  • Assign owner.
  • Link record.
  • State current safeguard.
Did You Know? GitHub advises tracking out-of-scope review feedback in a linked issue rather than expanding every pull request.
Important limit. Deferral is unsafe when the current change creates an immediate unacceptable risk.

How this skill transfers

Follow-up writing supports action plans. The same discipline supports examinations, further study and careers because students learn to distinguish a heading from evidence, an estimate from a final amount, a status from an outcome and general guidance from a personal decision.

Parents and mentors can help by asking the learner to show the exact line that supports each conclusion. They should not take over the account, application or decision. A strong final note uses two sentences: “The source confirms …” and “The source does not yet confirm …”.

CHAPTER 14 OF 14 · Transfer the skill

14. Turn review language into a reusable learning habit

Back to contents

Review is applied reasoning

The same structure—context, evidence, impact, severity and next action—works in school projects, lab reports, design critiques and career feedback.

After each review, save one anonymised example of a strong question, a strong blocker and a strong suggestion. This is where English becomes operational: the reader must keep the label, number, date, unit and source together instead of remembering only the most striking figure.

Practical example. A student uses the method to comment on a group presentation slide without rewriting the teammate’s work.

Use a source–meaning–action check

First copy the source wording exactly. Next explain what it means in this specific document. Then write the action, owner and deadline that follow. If any link is missing, pause and ask a precise question before paying, enrolling, travelling or submitting.

  • Protect confidentiality.
  • Classify comment.
  • Reflect on response.
  • Improve next review.
Did You Know? Review quality grows through deliberate examples, not only by reading more code.
Important limit. Never copy proprietary code or discussion into a personal portfolio.

How this skill transfers

Feedback literacy transfers across education and careers. The same discipline supports examinations, further study and careers because students learn to distinguish a heading from evidence, an estimate from a final amount, a status from an outcome and general guidance from a personal decision.

Parents and mentors can help by asking the learner to show the exact line that supports each conclusion. They should not take over the account, application or decision. A strong final note uses two sentences: “The source confirms …” and “The source does not yet confirm …”.

A seven-minute decision audit before you act

Minute 1–2: identify and date the controlled source

Open the current official record, not a screenshot copied into a chat. Name the person, account, property, course or journey to which it applies; copy the issue date, effective period and version; and confirm that you are authorised to view or act on it. If the identity or period is wrong, stop before doing arithmetic or interpreting conditions.

Minute 3–5: trace the evidence through the four reading routes

Use the routes in this guide as a compact audit: Understand the change; Write the comment; Collaborate and resolve; Transfer the skill. For each route, write one confirmed fact, one condition and one unresolved question. Keep every number beside its unit, every deadline beside its time zone or account rule, and every status beside the stage it describes. This prevents a plausible general explanation from replacing the actual record.

Minute 6–7: state the smallest safe next action

Choose one action that the source clearly supports: verify, compare, ask, pay, apply, prepare, monitor or preserve evidence. Name the owner and deadline. If the decision affects money, travel, tax, enrolment or personal data, use the official channel and save the acknowledgement. This short audit does not remove uncertainty; it makes uncertainty visible enough to manage responsibly.

Code-review workshop: improve three comments without weakening the technical point

Turn a vague objection into evidence

Replace “This is wrong” with the affected behaviour, triggering condition, likely impact and a reproducible check.

  • Name the file or behaviour.
  • State the condition.
  • Link the requirement.
  • Ask for a testable change.

Separate blockers from optional improvements

Label correctness, security or broken-contract problems differently from readability suggestions and personal preferences.

  • State severity.
  • Explain why.
  • Use “suggestion” or “nit” honestly.
  • Do not hide a blocker in soft language.

Close the discussion trail

After a change, verify the new evidence, acknowledge resolution and record any deferred work in the team’s normal system.

  • Re-read the diff.
  • Run or inspect tests.
  • Resolve only when answered.
  • Link follow-up work.

Advice for students, parents and mentors

Students can practise on a small program or group project. Review one decision at a time, quote the relevant requirement and suggest a verification method. The goal is to improve the work while keeping the author able to think.

Parents and mentors can model feedback that separates person, product and process: “The output differs from the task when this input is used” is more useful than “You are careless.”

New reviewers should ask for help when a change involves security, privacy, accessibility, concurrency or another area beyond their competence. Clear English includes naming the limit of one’s own review.

Frequently asked questions

Should every comment include a solution?

No. A reviewer can identify a risk and ask the author to investigate, especially when the author has more context. Explain the reasoning and desired outcome.

What is a blocking comment?

It identifies an issue that should be resolved before approval, such as incorrect behaviour, a broken requirement or a material safety or security concern. Use the team’s actual review conventions.

Is “nit” always harmless?

It should signal a genuinely non-blocking polish point. Do not label an important issue as a nit merely to sound pleasant.

Can I comment on the developer?

Keep criticism focused on the code, requirement, test or process. Personal judgments rarely add technical value and can damage collaboration.

When should reviewers meet instead of writing more comments?

When written exchanges are cycling, context is complex or tone is being misread. Record the resulting decision in the review afterwards.

Can AI write the review for me?

AI can help draft or summarise, but the human reviewer remains responsible for context, evidence, confidentiality, correctness and the final decision.

Useful next reading and primary sources

These current official sources were checked on 7 November 2026. The live account, provider, carrier or agency record controls a real decision.

Continue through eduKate

The best review comment makes the next technical conversation easier

A useful code review comment is not the longest or sharpest sentence. It is the one that lets another person locate the concern, understand why it matters, choose an appropriate fix and verify the result.

The reliable sequence is context, observation, evidence, impact, severity, next step and respectful closure.