falconGitHub

format-comment

Same as format-comment in Dart Code Metrics

Group
Style
Path
lint/style/format-comment
Default
Off, opt in
Origin
Dart Code Metrics
Rule
238 of 512

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 rejected.

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() {}

Configure format-comment

Set its severity in falcon.json. See the configuration guide.

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

Or silence one occurrence with a suppression comment; the reason is required.

example.dartdart
// falcon-ignore lint/style/format-comment: <reason>
  • implicit-call-tearoffsimplicit_call_tearoffs

    Explicitly tear off callable objects' call methods.

  • initializers-ordering

    Requires field initializers to follow their containing type's field declaration order by default.

  • leading-newlines-in-multiline-stringsleading_newlines_in_multiline_strings

    Flags a multiline string spanning several lines whose text does not start with a line break right after the opening quotes.

  • library-annotationslibrary_annotationsrecommended

    Requires library-targeted metadata to attach to a library directive.

  • library-nameslibrary_namesrecommended

    Flags a library name that is not lowercase_with_underscores.

  • library-prefixeslibrary_prefixesrecommended

    Flags import prefixes that are not lower_case_with_underscores.

  • lines-longer-than-80-charslines_longer_than_80_chars

    Flags source lines longer than 80 characters.

  • map-keys-ordering

    Flags literal string map keys that violate the configured order.