A good static analysis message states what is wrong, why it matters and how to fix it, in about one or two short sentences, and links to a longer page. The test is simple: could a developer fix the problem without leaving the editor? If not, the message is not finished.
Why wording changes outcomes
A finding is only useful if someone acts on it. A message like "Insecure call" sends the developer to search, guess or suppress. A message with a fix gets handled in a minute. Since false positive reports and suppressions both start with confusion, clear wording lowers both.
Three parts
- The problem. Name the specific thing in the code.
- The consequence. One clause about what can go wrong.
- The fix. The replacement or the check to add.
Weak and strong examples
| Weak | Stronger |
|---|---|
| Insecure call | runShell is called with a variable. Pass a fixed command and put user values in the argument list. |
| Bad crypto | MD5 is used for password storage. Use the password hashing helper in the auth package. |
| Violation of rule 42 | Do not call legacyAuth outside the auth module. Use sessionCheck instead. |
| Possible SQL injection | This query is built by joining strings. Use a parameterized query. |
Notice that the stronger versions name the code in front of the reader and point at something that exists in your repository. That second point is why internal rules can beat generic ones on usability.
How tools carry the message
Different engines support structured messages. ESLint rules can define messages keyed by messageId, and the docs note that rule metadata can include a URL where full documentation lives, which editors often use for a link on highlighted violations. The SARIF standard has matching fields for a rule: a short description, a full description, a help URI and message strings. Fill them in, because every downstream viewer can then show your wording.
A checklist before you ship
- Is the message under about 30 words?
- Does it avoid jargon the developer may not know, or define it?
- Does it name a fix that exists in this code base?
- Does the link go to a page with an example of bad and good code?
- Is the severity consistent with the wording? A message that says "may" should not break the build.
- Have you shown it to someone who did not write the rule?
Words to avoid
- "Insecure" with nothing after it.
- A rule id with no description.
- Blame wording such as "you forgot".
- Absolute claims when the rule is a heuristic. Say "may be reachable by user input" when the rule cannot prove it.
Maintain the page behind the link
A link to a page that has gone stale is worse than no link. Put the documentation next to the rule code and review it when the rule changes.
Quick check
How long should a rule message be?
Short enough to read in a glance, commonly one or two sentences. Put examples and edge cases on the linked page.
Should the message mention the CWE?
It can help security readers, but lead with the plain problem and fix. Put the identifier on the linked page or in the rule metadata.
Safeguard's scanning covers dependencies and SBOMs, and its reachability analysis helps show which findings your code can actually call. You can run a free scan on a repository.
Sources
Last reviewed: 19 October 2026.
