I just learned how to write PR reviews that keep them constructive without sounding like a jerk:
1. use "we" not "you",
2. keep every comment under 300 characters,
3. start each note with "nitpick", "suggestion", "optional"
4. stop doing fake praise as a technique
---
1. use "we" not "you"
Treat every PR note like a tiny product you are shipping and the product goal is simple:
Make it easy to act on and hard to misread.
Start by removing the 'you versus me' framing. Write in 'we' language so it feels like joint ownership of the codebase, not a personal correction.
Instead of saying 'You should rename this' or 'I would do it differently', write
- We should rename this to match the naming in UserService and AuthService,
- Can we change it to userId. That one swap changes the vibe fast.
2. short
cap each written note at 300 characters. Not 3 paragraphs, not your full reasoning.
Long text reads like a list of faults even when it is meant to help. If the reasoning matters, put one sentence in the PR and then ask for a 10 minute huddle or a quick call.
For example, we may want to avoid caching in this handler to prevent stale reads, can we talk for 10 minutes and pick an approach.
3. make intent explicit with normal words, not a legend
If something is optional, label it as optional in the first word. For example, use "nitpick" for style, "suggestion" for improvement, "blocker" for correctness or security, etc.
4. fake praise
Compliment sandwich feels like manipulation when the positive line is only there to cushion the hit.
Give real praise when it is real and tie it to a specific thing:
- Nice job on the early return in validateToken, it makes the error path clear.
- This ... looks good. That ... sounds like a good idea, but ... (it's fine)
Give critical feedback plainly and friendly, separate from praise. If something is broken, say what breaks and how to verify.
- Blocker, this can panic when user is nil, add a nil check and add a test that hits /login with a missing user record.