Label every review comment as blocking, optional or nit. Blocking means the change cannot merge until it is addressed. Optional means the author decides. Nit means minor polish that can be ignored. Clear labels keep reviews fast and make sure security concerns do not get lost among preferences.
Where the idea comes from
Google's published code review standard says minor polish points should be marked as a nit so authors know they may ignore them. It also says educational comments are welcome but, if they are not required for the change to meet standards, should be marked optional. Those two habits together give you most of what you need.
The same standard says reviewers should approve a change once it clearly improves the health of the codebase, even if it is not perfect, and that technical facts and data outweigh personal preference.
The three labels
Blocking. Something that must change. Use it for correctness bugs, missing authorization checks, unsafe handling of input, leaked secrets, and anything that makes the system worse.
Optional. A suggestion. The author may take it, decline it, or take it up later. Good for alternative approaches and learning points.
Nit. Cosmetic or very minor. Naming taste, small formatting points the linter missed. Never a reason to hold a merge.
A simple way to write them:
Blocking: this endpoint does not check that the caller owns the invoice. Optional: a lookup table might read better than this chain of conditions. Nit: rename tmp to parsedInput.
Why this helps security
Security comments stand out. When ten comments are all in the same voice, a serious one gets the same weight as a style note. Authors address the easy ones and miss the hard one.
Fewer stalled reviews. Google's guidance says not to let a change sit because author and reviewer cannot agree. When style comments cannot block, fewer standoffs happen.
Reviewers think before blocking. Choosing the label forces the question: does this actually make the system worse?
Resolving disagreement
The Google standard offers a path. First try to reach agreement. If that stalls, talk face to face or on a call and record the outcome on the change. If still stuck, escalate to a wider team, a tech lead, a maintainer or a manager. The outcome should be written down so the same argument does not recur.
For security disagreements, add one rule: when a reviewer says an issue is a vulnerability, the author brings evidence if they disagree, such as a test showing the case is not reachable. Opinion alone should not clear a blocking security comment.
Team habits
- Agree the three labels in your contributing guide.
- Let the style guide and linter settle style, as Google's standard says the style guide is the final authority on style.
- Resolve every blocking comment explicitly before merge. GitHub branch protection can require conversation resolution if you want enforcement.
- Review the labels occasionally. If most comments are blocking, either the code or the culture needs attention.
Automated reviewers
The same labels work for comments from automated tools. Decide which tool findings are blocking by policy, such as a new critical vulnerability, and leave the rest as optional.
Safeguard's policies and gates can make the blocking category automatic for dependency and vulnerability findings. The free scan is at gold.safeguard.sh/scan.
Quick check
Who decides if a comment is blocking?
The reviewer proposes it. If the author disagrees, they discuss, and unresolved cases follow the escalation path. Security issues need evidence either way.
Can nits be skipped entirely?
Yes. Google's standard marks them as ignorable. If one nit keeps recurring, add it to the linter.
Sources
Last reviewed: 19 October 2026.
