/dart-long-lines

name: dart-long-lines
description: |-
  Guidelines for handling long lines in Dart code to adhere to the 80-column
  rule. The `lines_longer_than_80_chars` lint.
license: Apache-2.0
key_features:
  - 80-column rule compliance
  - Line length refactoring
  - Linter rule enforcement

Dart Long Lines

1. When to use this skill

Use this skill when:

• Writing Dart code that might exceed the 80-column limit.
• Refactoring code to comply with the `lines_longer_than_80_chars` lint.

Reference: https://dart.dev/tools/linter-rules/lines_longer_than_80_chars

When NOT to use (Abstention Guardrails)

Do NOT break lines or alter code when:

• **Unbreakable URLs & URIs**: Lines contain long HTTP/HTTPS URLs, import URIs,

or file paths where breaking them across lines would invalidate the link.

• **Complex Regular Expression Literals**: Long RegExp patterns

(`RegExp(r'...')`) where inserting whitespace or line breaks changes the matching semantics.

• **ASCII Art, Tables, or Preformatted Diagrams**: Preformatted text blocks,

table rows, or ASCII diagrams inside comments or strings where wrapping lines destroys visual alignment.

• **Prior to Automated Formatting**: Do NOT manually break code lines before

running `dart format`. Let `dart format` handle code wrapping automatically; only manually wrap comments, docs, and multi-line strings that the formatter does not re-wrap.

Discovery

To find lines that exceed the limit:

Automated Analysis

The most reliable way to find long lines is to use the Dart analyzer:

• **Command**: `dart analyze`
• **Lint**: `lines_longer_than_80_chars`

Manual Search

To search for long lines using regex:

• **Regex**: `^.{81,}$` (Matches any line with 81 or more characters).

2. Guidelines

Format First

Always run `dart format` before manually breaking long lines. The formatter often automatically fixes long lines, especially in generated code, and applies standard Dart styling rules.

Code Comments

Break long code comments (`//`) cleanly at word boundaries to ensure lines do not exceed 80 characters. Maintain tight formatting and avoid unnecessary vertical space.

Documentation Comments (`///`)

• Apply the same line-breaking rules as for code comments.
• Avoid breaking markdown link blocks like `[name]` or

`[text](http://example.com)` across lines. Place them on their own line if they exceed the limit.

• Start doc comments with a single summary sentence, followed by a blank line

before the rest of the comment. It is okay to break this first sentence across multiple lines to fit the 80-column limit.

• Avoid unresolved references or dangling sentences.

Long Strings

• Use adjacent string literals (e.g., `'part 1 ' 'part 2'`) to break long

strings. Break at word boundaries.

• If a single-line string contains newline characters (`\n`) or if there are

consecutive `print` statements, consider migrating to a multi-line string literal (`'''`).

Format and Analyze After Changes

• Run `dart format` and `dart analyze` after making changes.
• Be aware that splitting strings may trigger new lints (e.g.,

`prefer_single_quotes` if a double-quoted string is split into parts that no longer contain single quotes).

3. Examples

Documentation Comment Link

**Avoid:**

/// This is a long doc comment that contains a link to [a very long
/// URL](http://example.com/very/long/url/that/exceeds/eighty/chars).

**Prefer:**

/// This is a long doc comment that contains a link to [a very long URL][ref].
///
/// [ref]: http://example.com/very/long/url/that/exceeds/eighty/chars

Adjacent String Literals

**Prefer:**

final longString = 'This is a very long string that needs to be broken '
    'across multiple lines to stay under the limit.';

Multi-line String Migration

**Avoid:**

print('This is line 1\nThis is line 2 that is also quite long\nThis is line 3 which makes the whole thing exceed eighty characters');

**Prefer:**

print('''This is line 1
This is line 2 that is also quite long
This is line 3 which makes the whole thing exceed eighty characters''');