A security bot should comment rarely, on the exact changed line, in plain words: what is wrong, why it matters here, and how to fix it. It should offer a clear way to dismiss a finding and stay quiet when nothing new appears. A comment that is easy to act on gets read. A noisy one gets muted.
Treat the bot as a reviewer, not a scanner
A scanner prints everything it knows. A reviewer chooses what is worth a person's attention right now. Pull request comments sit in the middle of someone's working day, so they should follow reviewer manners.
Google's public code review guidance says to comment on the code and not the person, to explain the reasoning behind a point, and to label minor items so authors can tell what is required from what is optional. A bot cannot be rude in the human sense, but it can be vague, repetitive and loud. The same rules apply.
The four parts of a useful comment
Each comment should answer four questions in the order a developer asks them.
- What did you find? One sentence, naming the function, package or pattern.
- Why does it matter in this change? Say whether the code path is reachable or the input is user controlled.
- What should I do? A concrete fix, ideally a suggested change the author can apply directly.
- What if you are wrong? A visible way to dismiss with a reason.
GitHub supports suggested changes in review comments, where the pull request author can apply the edit from the comment itself. That turns a complaint into a one click action.
Place the comment where the cause is
Put the comment on the line that introduced the problem. A finding in an untouched file belongs in a summary, not as an inline note on a file the author never opened. Inline comments that point at code the author did not write feel unfair and are usually ignored.
For dependency changes, comment on the manifest line that added or bumped the package, and name the version that fixes it.
Batch and cap
GitHub notes that batching review comments into one submitted review avoids sending a separate notification for each. A bot that posts ten separate comments sends ten alerts. Group findings into one review where the platform allows it, and set a cap, for example five inline comments per push, with the rest in a summary link.
| Design choice | Noisy version | Quiet version |
|---|---|---|
| Volume | Every finding inline | Capped, ranked by severity |
| Repeats | Re-posted on every push | Posted once, updated in place |
| Tone | Alert style text | Short, specific, reasoned |
| Exit | None | Dismiss with a reason |
Try it yourself
Click through it at your own pace, or open it full screen.
Watch how the pull request check reports its result, and compare it with the comment shape above.
Where Safeguard fits
Safeguard can run dependency scanning and reachability analysis on pull requests, with policies you set for what blocks and what only informs. You can try a free scan to see the findings format on your own code.
Quick check
How many inline comments is too many?
There is no fixed number in any standard. A cap of a handful per push, with the rest summarised, is a sensible starting point that you tune from developer feedback.
Should a bot approve a pull request?
Treat that as a policy decision for your team. Many teams prefer a bot to report status and leave approval to a person.
Sources
- Google Engineering Practices: How to write code review comments
- GitHub Docs: Commenting on a pull request
Last reviewed: 19 October 2026.
