Writing Kind, Specific Review Comments
Introduction
Welcome to Comments That Get Merged. We’re beginning a lesson on writing review comments that help improve code while keeping the conversation respectful. We’ll follow one ticket-renaming example from the initial finding through the requested change, its tests, and the final demonstration. By the end, we’ll be able to connect a specific behavior to its impact and offer a clear next step.
What Makes Review Feedback Kind and Specific
A useful review comment focuses on the code, not the person who wrote it. It points to behavior we can observe, explains why that behavior matters, and asks for a focused next step. This gives the author enough information to respond without guessing what the reviewer means.
For this ticket example, we can think of feedback in three parts:
- Behavior: What does the proposed code do?
- Impact: Who might be affected, and how?
- Request: What small change would address the concern?
As you may recall from earlier courses, strong review feedback is grounded in evidence. Here, the evidence is a title containing only spaces, and the impact is that support staff may have trouble identifying the ticket.
Reading the Review as a Timeline
A review record spans several moments. If we mix them up, a comment written about an earlier version can look like a defect in the code we are reading now. This example follows one sequence:
Original proposal → Reviewer request → Author revision → Verified resolution
The finding and comment below were written against the original proposal, which assigned the new title without any check:
The rename() code shown later in this lesson is the author revision, and the resolution records what was verified after that revision.
Inspecting the Completed Review: The Finding in Ticket.rename()
The review identifies a risk in the originally proposed rename behavior: it accepted a title made only of spaces. That is a specific claim about what the method allowed, not a judgment about the person who wrote it. The finding also explains why the behavior matters in this support ticket example.
In REVIEW.md, the finding is:
This finding connects a named behavior, rename, to an observable risk: a title with no meaningful text. It then describes the practical effect: a ticket that is difficult to identify in a list. That impact helps the author understand why the issue deserves attention.
