jww-swift-style

JWW Swift スタイル

最優先のルール：変更対象のコードの隣に置いても違和感のないコードを生成します。 最も近い周辺の Swift ソースと、適用される AGENTS.md が最終的な基準です。以下は、周辺のコードに明示されていない場合に限るデフォルトです。主に、新しいトップレベルファイルが対象です。

入力と出力

• 対象となる Swift ファイルまたは差分、近くにある比較対象のソース、適用されるすべての AGENTS.md を入力として受け取ります。
• ローカルの規約に合った最小限の Swift の編集、またはスタイルレビューを行います。編集した場合は、実施した検証を明記します。

作成前に

1. 対象ファイルと、近くにある比較対象のファイルを読みます。適用されるネストした AGENTS.md もそれぞれ読みます。
2. 既存の構成、インポートの順序、アクセス制御のスタイル、すべての MARK とセクション区切りを維持します。無関係なフォーマット変更やスタイルの整理は行いません。
3. 対象プラットフォームとモジュールに適した API を選択します。限定的なプラットフォーム条件分岐が必要な場合を除き、モジュールがサポートするすべてのプラットフォームで共有コードが動作するようにします。

ソースの配置

• 4 スペースのインデントを使用し、宣言や論理的な手順をグループ化するために空行を入れます。
• 行の長さの上限には、適用される SwiftLint の line_length 設定を使用します。設定されていない場合は、デフォルトで 150 文字とします。無効化された line_length ルールを含め、明示的なリポジトリのオーバーライドに従います。
• プロジェクトのインデント設定を使い、インデントと継続行の配置が Xcode の Control-I（再インデント）の出力と一致するようにします。呼び出し、宣言、条件、チェーン、クロージャに適用し、改行位置はラップの例に従います。
• 重要な型にセクションを追加するのは、リポジトリで以下に示す区切りスタイルがすでに使われている場合に限ります。近くのファイルに正確に合わせます。// MARK: の行だけを使う場合もあれば、その後にボックスコメントを続ける場合もあります。型を拡張する際は、既存のセクション名と順序を維持します。

// MARK: View Lifecycle
// ====================================
// View Lifecycle
// ====================================

• 拡張ファイルでは、近くのファイルに合う場合、ファイルスコープでも同じ区切りを使い、文脈に合ったセクション名を付けます。
• 新しいトップレベルファイルでは、主要な型を 1 つにすることを推奨します。スタイルだけを理由に既存のファイルを分割せず、補助的な型、拡張、プロトコルについては、近くのコードのグループ化の規約に従います。
• 新しいファイルを作成する場合、目的が明確な拡張ファイルには Type+Purpose.swift という名前を付けます。周辺のモジュールですでに関連する拡張を主題ごとにまとめている場合は、それに従います。
• イニシャライザー、ライフサイクルメソッド、アクション／デリゲートメソッド、プライベートな便利機能は、ローカルの順序に従います。単純な保存プロパティは、それらのセクションより前に配置します。
• ファイルを囲むコードの self. の規約に従います。ビューコントローラーのコードでは、ファイル内で明示的に self. を使っている場合は一貫して使用します。全体にわたって追加または削除しないでください。
• SwiftLint の設定で always_on_same_line または always_on_line_above が定義されている場合は、そのルールに従います。それ以外の場合は、@available、@Test、@ViewBuilder、@Model を宣言の前の行に置きます。プロパティラッパーの属性は宣言と同じ行に置き、宣言が設定された上限を超える場合は、ローカルの折り返し方に従います。
• ローカルの折り返し方と設定された行の長さの上限に従い、無関係なコードの折り返しを変更しません。折り返し方が明確でない場合は、例として references/line-wrapping.md を読みます。リポジトリの複雑度の上限に従い、正当なローカル例外が残る場合に限り、最小スコープの swiftlint:disable を使用します。

命名、アクセス制御、ドキュメント

• 明確で慣用的な Swift の名前を使い、周囲のターゲットに合わせた明示的なアクセスレベルを指定します。インターフェースでより広いアクセスが必要な場合を除き、実装の詳細は private にします。
• 型の役割に合う場合は、サブクラス化しない参照型に final を指定します。
• 呼び出し元が値を監視する必要はあっても変更する必要がない場合は、private(set) を使います。
• パブリックまたは共有 API には英語のドキュメントコメントを記述し、意図や自明でないプラットフォーム上の制約にはコメントを付けます。コードを繰り返すだけのコメント、時系列を示すラベル、LLM やプロセスへの言及は追加しないでください。
• 有用なコメントと MARK、セクション区切りは維持します。コメントが不正確になった場合にのみ更新します。

Swift と Apple API

• デプロイメントターゲットですでに利用できる、標準の Swift 言語機能とプラットフォームフレームワークを優先します。定型的な作業にサードパーティの依存関係を導入することは避けます。
• 必須の早期終了には guard を使い、速やかに戻ります。想定される失敗の処理を明示します。
• クロージャーと非同期処理は読みやすく保ちます。保存されたコールバックやライフサイクルによってコントローラーが不必要に保持される可能性がある場合は、self を弱参照でキャプチャします。
• 共有コードでは #if os(...) または #if targetEnvironment(...) を必要最小限で使い、可能な限り一貫した共有インターフェースを維持します。
• ローカルの可用性チェックのスタイルに合わせます。明示的な要件がない限り、デプロイメント互換性を変更しないでください。

テスト

• 既存のテストファイルのフレームワークと構成に従います。XCTest ターゲットに新しいテストを追加する場合、ターゲットが移行中でなければ XCTest を使います。それ以外の場合は Swift Testing（import Testing、@Test、#expect、#require）を優先します。
• テストは対象を絞り、動作を示す名前を付け、リポジトリに既存のフィクスチャとヘルパーを使います。動作を変更しない場合は既存の XCTest テストを維持し、スタイル上の理由だけで移行しないでください。

最終確認

Swift コードを提示する前に、変更した箇所の前後を読み直し、区切り、ローカルでの順序、インポート、可視性、プラットフォームの境界、関連する SwiftLint の制限が維持されていることを確認します。実際に変更を加えた場合は、設定されているリポジトリの対象を絞った lint コマンドに加え、最も関連性の高いビルドまたはテスト検証を実行します。