Give security feedback in code review by commenting on the code rather than the person, explaining why the change matters, labelling how serious it is, and noting what was done well. A comment that names the risk and suggests a fix lands better than one that only says "insecure".
Start from published review guidance
Google's public engineering practices on writing review comments give a useful base: be kind, explain your reasoning, balance direct instructions with pointing out problems, and label comment severity. Its example contrasts a blaming question with a neutral statement about the code. Security comments benefit from the same habits, with one addition: say what the attacker could do.
Rewrite examples
| Harsh | Better |
|---|---|
| "Why would you build SQL by hand? This is injectable." | "This query concatenates the user id into the string, so a crafted id could change the query. A parameterised query avoids that. Example: link to the pattern used in the orders module." |
| "You forgot auth." | "This endpoint has no authorization check, so any logged in user could read another customer's record. Could we add the same ownership check used in the invoice handler?" |
| "Never log tokens." | "The token appears in the debug log line, and logs are readable by more people than the database is. Could we log the last four characters only?" |
Notice the shape: observation, consequence, suggestion with a pointer.
Label severity
Make it clear which comments block the merge. A simple scheme works:
- Blocking: a real vulnerability or a policy violation. Must be fixed before merge.
- Suggestion: would improve safety, not mandatory now.
- Question: you want to understand something before deciding.
- FYI: a note for later, no action in this change.
Without labels, authors tend to read every comment as mandatory, which stalls reviews or leads to quiet resentment. The Google guidance makes the same point about nit, optional and FYI labels.
Teach once, then link
If you leave the same comment often, write a short internal note on the pattern and link to it. "See our upload handling guide" is faster than retyping, and it is less personal. Over time, the team stops making the mistake.
Praise what is good
Security reviewers mostly speak up about problems. Add a line when someone uses an existing control, adds a test for a bad input, or removes a risky dependency. Reinforcement is cheap and it teaches as well as correction does.
Know when to go off thread
If a finding is serious, such as a leaked credential, a short private message with the urgent steps (rotate it, then fix it) is better than a long public comment thread. Keep the tone calm and practical. The goal is a fix, not a reprimand.
Reduce comment load
A review with thirty security comments is rarely read carefully. Group related issues, handle repeated patterns with one comment plus a list of locations, and let automated checks catch the mechanical ones so human reviewers can focus on design and logic.
Safeguard runs dependency and policy checks on pull requests so reviewers can spend their comments on the design questions a tool cannot judge. The free scan at gold.safeguard.sh/scan is a way to see that output on your own project.
Quick check
Should security comments be blocking by default?
When the issue is a real vulnerability or a policy breach. Label the rest as suggestions so authors can prioritise.
Is it fine to ask the author to explain their code?
Yes, and a good answer often means the code should be clearer. Ask about the code, not the person.
Sources
Last reviewed: 19 October 2026.
