Comment Style check
The Comment Style check reads the comments a comment layer locates and
holds them to the limits under style.comments in the voice profile at the
point the comments sit at. A profile without that section asks for nothing,
and the check reports its analyzers as not requested.
comment.sentence-length: a sentence over the minor word limit is a minor finding, and one over the major limit a major finding. The finding points at the sentence inside its comment and quotes it.comment.length: a comment over the word limit for what it documents is a major finding. The doc comment of a package or module, a declaration's doc comment and every other comment each have a limit of their own.comment.density: in a check scoped to a diff, a change that adds at least the minimum number of comment lines to a file, and more comment lines for each code line than the ratio allows, is a major finding. A line holding a comment and nothing else is a comment line, a line holding anything outside a comment is a code line, and the package doc comment, a directive and a blank line count as neither.
A sentence is found with the UAX #29 sentence break over the comment's prose.
The lines a comment wraps a sentence over are joined first, because the
sentence break ends a sentence at every line break. A blank line, a line of
code, and a divider line such as ── Section ── end a sentence, and a
divider's title is a sentence of its own. A heading, a list item and a
documentation tag such as @param each start one. A word holds a letter or a
digit, so a code span, a reference, a link or a dash standing alone is never
counted.
Rules
A finding carries one of these rule ids. The family is comment, which differs from the check id the code registers.
| Rule | Severity | Reports | Fix |
|---|---|---|---|
comment.sentence-length | minor | A sentence in a comment holds more words than the limit under | Split the sentence, or cut the words it does not need. |
comment.length | major | A comment holds more words than the limit for what it documents. The doc comment of a package or module, a declaration's doc comment and every other comment each have a limit of their own. | Shorten the comment, or move what it explains to the documentation it belongs in. |
comment.density | major | In a check scoped to a diff, a change adds at least the minimum number of comment lines to a file, and more comment lines for each code line than the ratio allows. | Cut the comments the change adds to what the code needs, or raise the ratio in the voice profile. |
This check takes no flag of its own.
Processing notes
Each analyzer catches canaries built from the limits in force beside every file. The wrapped sentence canary is one sentence over three lines, so a check that ends a sentence at a line break misses it.
In a check scoped to a diff, the limits apply to the comments the change touched.
Density counts lines from where the comment reader places each comment, never from comment markers, and its canary is a block comment no marker opens. A check over whole files reports density as unsupported.
Findings count toward the same severity gate as any other finding.
kapi checkfails on a critical finding by default, andkapi check --shipfails its checks gate on a major one.
Limitations
Reads comments only; the blocks a format reader extracts are never held to comment limits.
Needs the UAX 29 sentence break, which a build without ICU lacks. The sentence check then did not run, and the run is not a pass.
Counts words by whitespace, so a language written without spaces between words is held to the limits as one long word per stretch.
← Back to the Check Reference