dart-best-practices

Dart のベストプラクティス

1. このスキルを使う場面

以下の場合にこのスキルを使います。

• Dart コードを記述またはレビューするとき。
• 慣用的な Dart の使い方についてガイダンスを探しているとき。

使用しない場面（適用を控えるためのガードレール）

以下の場合は、このスキルを適用したり、コードをリファクタリングしたりしないでください。

• 公開 API の破壊的変更：公開パッケージの公開 API コントラクト、戻り値の型、またはパラメーターのシグネチャを変更するリファクタリングを、調整済みのメジャー SemVer アップなしに行う場合。
• 形式にこだわったマイクロ最適化：理論上のわずかな効果のために、明確で読みやすいコードを書き換える場合（例：単純な 1 行のログメッセージで明確な文字列連結を複数行の引用符に置き換える）。
• ドメイン固有のファイルやコード生成ファイル：生成ファイル（*.g.dart、*.freezed.dart、protobuf など）、または行の長さや文字列のレイアウトがコードジェネレーターによって管理されているファイル。
• 公開インターフェイスにおける明示的な型注釈：明示的な型が公開 API の表面を説明する場合や、複雑なジェネリクスの曖昧さを解消する場合に、型注釈を var や final に置き換えること。

2. ベストプラクティス

複数行文字列

文字列を + と \n で連結するよりも、複数行文字列（'''）を使うことを推奨します。特に、SQL クエリ、HTML、PEM エンコードされたキーなどの大きなテキストブロックに適しています。自然な位置で改行できるため、読みやすさが向上し、lines_longer_than_80_chars の lint エラーも回避できます。

避けるべき例：

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

推奨例：

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

行の長さ

Markdown ファイルやコメントも含め、80 文字を超える行は避けてください。これにより、分割画面や小さな画面でも横スクロールせずにコードを読みやすくできます。

推奨事項： テキストの折り返しは 80 文字を目安にしてください。長い URL や、途中で分割できない識別子は例外とします。

検出方法

複数行文字列

複数行文字列の候補を見つけるには、改行を含む文字列連結を検索します。

• 正規表現：['"]\s*\+\s*['"]
• 正規表現：\+\s*['"].*\\n

行の長さ

• analyzer の lines_longer_than_80_chars lint を利用してください。

関連するスキル

• dart-modern-features：パターンマッチング（複雑な JSON の抽出に便利）、レコード、switch 式など、最新の Dart 機能を慣用的に使う方法について説明します。