You leave a dozen comments on a pull request. Two of them are real problems. The rest are thoughts: a name you might have chosen differently, a question about why a helper exists, a pattern you happen to prefer. To you the difference is obvious. To the author, every comment looks the same.
So they do one of two things. Some treat everything as mandatory, spend a day reworking a design that was fine, and quietly resent you for it. Others treat everything as optional, argue with the two comments that mattered, and merge with a real problem still in it. Both are rational responses to feedback that never said how much it weighed.
The fix takes a few characters. Say, on each comment, what kind it is.
Needs changing, when you would not approve the merge as it stands. A bug, a missing check, something that will hurt somebody later.
Suggestion, when you have a preference and would be happy either way. The author decides, and you mean it.
Question, when you genuinely do not know and want to understand. Why is this cache here? can read as an accusation or as curiosity, and the label settles which.
Some teams write these as prefixes, some use the review tool's own features. The format matters much less than the habit.
Two things follow once you start. Your reviews get faster, because the author knows exactly what stands between them and done. And you get more honest with yourself, because you have to decide, comment by comment, whether you actually care. Many comments that felt important turn out to be suggestions once you are forced to name them. A few that you almost left as a gentle aside turn out to be blocking, and now you say so plainly instead of hoping they notice.
Close the review with one summary line. Approve once the two changes are in, everything else is your call. That sentence is often the most useful part of the whole review.
Being clear about weight is a kindness. People can handle a direct note. What wears them down is guessing.
– Asael Shinder
Top comments (0)