dart-best-practices - SKILL.md Agent Skill

name: dart-best-practices description: |- General best practices for Dart development. Covers code style, effective Dart, and language features. license: Apache-2.0

Dart Best Practices

1. When to use this skill

Use this skill when:

Writing or reviewing Dart code.
Looking for guidance on idiomatic Dart usage.

2. Best Practices

Multi-line Strings

Prefer using multi-line strings (''') over concatenating strings with + and \n, especially for large blocks of text like SQL queries, HTML, or PEM-encoded keys. This improves readability and avoids lines_longer_than_80_chars lint errors by allowing natural line breaks.

Avoid:

final pem = '-----BEGIN RSA PRIVATE KEY-----\n' +
    base64Encode(fullBytes) +
    '\n-----END RSA PRIVATE KEY-----';

Prefer:

final pem = '''
-----BEGIN RSA PRIVATE KEY-----
${base64Encode(fullBytes)}
-----END RSA PRIVATE KEY-----''';

Robust extractions of values from a Map with Switch Expressions

When parsing Map structures or JSON (e.g., from jsonDecode), use switch expressions with object patterns for deep validation and extraction. This is clearer and safer than manual is checks or as casts.

Avoid (Unsafe Access):

final json = jsonDecode(stdout);
if (json is Map &&
    json['configuration'] is Map &&
    json['configuration']['properties'] is Map &&
    json['configuration']['properties']['core'] is Map) {
  return json['configuration']['properties']['core']['project'] as String?;
}
return null;

Prefer (Deep Pattern Matching):

return switch (jsonDecode(stdout)) {
  {
    'configuration': {
      'properties': {'core': {'project': final String project}},
    },
  } =>
    project,
  _ => null,
};

This pattern cleanly handles deeply nested structures and nullable fields without the complexity of verbose if-else blocks or the risk of runtime cast errors.

Line Length

Avoid lines longer than 80 characters, even in Markdown files and comments. This ensures code is readable in split-screen views and on smaller screens without horizontal scrolling.

Prefer: Target 80 characters for wrapping text. Exceptions are allowed for long URLs or identifiers that cannot be broken.