What makes a review comment worth reading?
A specific observation, a clear consequence, and a useful next step. The rest is editing.
A review comment asks for another person's attention. That is a good reason to be deliberate about what we put in it. The aim is to help someone make a decision.
Start with the behavior
“This looks wrong” leaves the author with the investigation. A more useful comment says what the code will do, under which condition, and why that result matters.
Try describing the observable outcome first. If an empty list reaches this function, does the caller receive a missing value? If a request fails, does the screen still show success? Specific behavior gives the discussion something both people can examine.
Separate evidence from a question
Sometimes the surrounding code establishes a problem. Sometimes an important detail is missing. Those deserve different comments. Say what you found and make the uncertainty visible.
A precise question can be more useful than a confident guess.
A comment such as “Does the caller guarantee a non-empty list?” invites the author to supply the missing contract. If the guarantee exists, it may belong in a type, an assertion, a test, or a short explanation close to the code.
Leave a next step
- Suggest a concrete change when the fix is clear.
- Ask a focused question when context is missing.
- Explain whether the concern affects behavior or expresses a preference.
- Keep each comment about one decision.
Read your comment once from the author's side before posting it. Can they tell what you noticed? Can they understand its consequence? Do they know what to do next? If those answers are clear, the comment has earned its place.
Every line. Worth a second look.