A diff is only half the story.
The most useful review starts with the lines that changed. Then it looks a little further.
A pull request gives a change a boundary. A few files, a handful of lines, a description of what should happen next. It is a useful place to start reading. It is rarely the whole story.
Read around the change
A function can look reasonable on its own and still surprise its caller. A new return value might mean something different to the code that consumes it. An early return might skip cleanup. The surrounding code is where those expectations live.
Before commenting on a line, follow one path into it and one path out of it. Who calls this function? What do they expect back? Which assumption does this change preserve, and which does it disturb?
The useful question is often one file away from the changed line.
Follow the assumption
Consider a helper that sends an invitation. The request finishes and the helper returns success. The calling screen then tells the user that the invitation was sent.
const response = await fetch(invitationUrl, options);
if (!response.ok) {
throw new Error(`Invitation failed: ${response.status}`);
}
return { sent: true };The status check connects the network result to what the caller is about to claim. Without it, an HTTP error can travel through the success path. Seeing both the helper and its caller makes the consequence clear.
Bring the context into the comment
A finding becomes useful when another developer can follow the reasoning without repeating the whole investigation. Explain the assumption, show where it breaks, and suggest the smallest next step.
- Name the behavior that could change.
- Point to the surrounding code that depends on it.
- Describe a concrete case that exposes the issue.
- Offer a fix or a question the author can act on.
That is the perspective behind Inkspect: pay attention to the change, and to the connections that give it meaning. Every line deserves a second look. Sometimes that means looking beyond the line itself.
Every line. Worth a second look.