What belongs on the page a security comment links to?

A security comment should stay short and link to a page for the rule. That page needs a plain explanation of the risk, a bad and a good code example, how to fix it, when it is safe to dismiss, and an owner. Written once, it saves every future comment from repeating the same lecture.

Why a separate page

Long comments get skipped. Short comments with no depth get dismissed because the reader cannot tell if they are right. A link resolves the tension: the comment gives the action, the page gives the reasoning for anyone who wants it.

Google's public review guidance says that explanations written only in the review tool are not helpful to future readers of the code. The same is true for findings: if the knowledge lives only in a thread, the next developer will meet the same finding with no context. A durable page fixes that.

A template for a rule page

1. Name. The same label used in comments, so searching works.
2. What it means. Two or three plain sentences, no jargon without a link.
3. Why it matters. A short, realistic scenario.
4. Bad example. A few lines of code that trigger the rule.
5. Good example. The corrected version.
6. How to fix. Steps, including the automated fix if one exists.
7. When to dismiss. Honest cases where the finding is a false positive or acceptable.
8. Owner and last review date. So readers know it is maintained.

Show it in a short code block so it is quick to scan.

Rule: sql-string-concat
Bad:  query = "SELECT * FROM users WHERE id = " + user_id
Good: query = "SELECT * FROM users WHERE id = %s"; run(query, (user_id,))

Keep pages short and findable

Include the dismissal guidance

The most trusted pages are honest about false positives. State the real conditions under which a finding does not apply, such as test fixtures or values that never reach user input. This builds credibility and reduces arguments in threads.

Link to your own conventions

If your team has a standard helper or library for the safe pattern, link to it and show how to import it. A rule page that says "use X" and points to X is better than one that says "do not do Y".

Maintain it like code

Keep the pages in a repository, review changes through pull requests, and connect rule changes to page updates. If a rule is retired, redirect its page. Treat pages with high dismissal rates as a prompt to improve either the rule or the explanation.

Safeguard findings include context that you can reference in rule pages, and guardrails you can configure per policy. Try a free scan and see which findings would need pages.

Quick check

Sources

• Google Engineering Practices: How to write code review comments

Last reviewed: 19 October 2026.