falcon

Rules / Style / format-comment

format-comment

lint/style/format-comment
recommended
Same as format-comment · Dart Code Metrics

Flags comments that are not formatted as complete sentences.

Sentence-cased, terminated comments read consistently and signal a finished thought rather than a scratch note. A comment should start with an uppercase letter and end with ., !, ?, or :. Consecutive comment lines are joined into one block and split into sentences before checking, so a sentence that wraps across several /// lines is judged as a whole and continuation lines are never flagged on their own. Both // line comments and /// doc comments are checked by default.

Options

only_doc_comments (bool, default: false) — when true, only /// doc comments are checked.

ignored_patterns (list of regexes, default: []) — a comment matching any of these patterns is skipped entirely; invalid patterns are ignored.

Invalid

example.dartdart
// Header regular comments are ignored (only_doc_comments); the doc comments
// below are the real fixtures.

/// lowercase start makes this an invalid sentence.
void badLower() {}

/// Missing terminal punctuation
void badNoPunct() {}

/// A leading sentence that wraps but the whole block never
/// terminates with any punctuation
void badWrapped() {}
Prefer formatting comments like sentences
3
4/// lowercase start makes this an invalid sentence.
Prefer formatting comments like sentences
6
7/// Missing terminal punctuation
Prefer formatting comments like sentences
9
10/// A leading sentence that wraps but the whole block never

Valid

example.dartdart
// Fixtures for the format-comment rule, configured with only_doc_comments:true.
// Regular // comments (like this header) are NOT checked, so lowercase and
// unterminated regular comments never fire here.

/// A correctly formatted single-line doc comment.
void single() {}

// this regular comment is lowercase and unterminated but is skipped entirely
// because only_doc_comments is enabled.
void regularIgnored() {}

/// This is a long description that wraps across two source
/// lines and still ends with proper terminal punctuation.
void wrapped() {}

/// {@template my.macro}
/// Body text goes here.
/// {@endtemplate}
void macro() {}

/// A block whose first sentence ends early. And a second wrapped
/// sentence that also terminates cleanly.
void twoSentences() {}

/// Guarded here and here and here and here and here and so on now: fine.
void colonSingleLine() {}

/// Guarded here and here and here and here and here and so on now:
/// an unguarded throw would unwind to the zone handler here right now.
void colonWrapped() {}

How to configure

Set the severity of format-comment in your falcon.json:

falcon.jsonjson
{
  "linter": {
    "rules": {
      "style": {
        "format-comment": "error"
      }
    }
  }
}

Related