Swift API Design Guidelines スキル

概要

このスキルを使用して、使用時に明確で、呼び出しサイトで流暢であり、確立された Swift の命名およびラベル付けの慣例に準拠した Swift API を設計およびレビューします。読みやすさ、明確な意図、および宣言、呼び出しサイト、ドキュメントコメント全体における一貫性を優先します。

作業の決定木

1) 既存コードのレビュー

• 宣言だけでなく、宣言と呼び出しサイトを一緒に検査します。
• 命名の明確性と流暢さを確認します（references/promote-clear-usage.md、references/strive-for-fluent-usage.md を参照）。
• 引数ラベルとパラメータ命名を確認します（references/parameters.md、references/argument-labels.md を参照）。
• ドキュメントコメントとシンボルマークアップを確認します（references/fundamentals.md を参照）。
• 慣例とオーバーロード安全性を確認します（references/general-conventions.md、references/special-instructions.md を参照）。

2) 既存コードの改善

• あいまいで、冗長で、役割が不明確な API の名前を変更します。
• ラベルをリファクタリングして、呼び出しサイトの文法的な読みやすさを向上させます。
• 役割が不明確なパラメータを役割ベースの名前に置き換えます。
• 弱い型付けではあいまいになるオーバーロードセットを解決します。
• ドキュメント要約を強化して、動作と戻り値を正確に記述します。

3) 新機能の実装

• 宣言を確定する前に、使用サイトの例から始めます。
• 呼び出しが明確な英語フレーズとして読まれるように、基本名とラベルを選択します。
• デフォルト値は一般的な使用法を簡潔にするときだけ追加します。
• mutating/nonmutating のペアを一貫した命名で定義します。
• すべての新しい宣言に簡潔なドキュメントコメントを追加します。

コアガイドライン

基本原則

• 使用時の明確性が最優先事項です。
• 明確性は簡潔さよりも重要です。
• すべての宣言にはドキュメントコメントが必要です。
• 要約は、その宣言が何をするのか、何を返すのか、何にアクセスするのか、何を作成するのか、または何であるのかを述べるべきです。
• 認識された Swift シンボルマークアップ（Parameter、Returns、Throws、Note など）を使用します。

明確な使用法の促進

• あいまいさを避けるのに必要なすべての単語を含めます。
• 特に型の繰り返しを避けて、不要な単語を削除します。
• パラメータと関連する型に、型ではなく役割で名前を付けます。
• 型情報が弱い場合（Any、NSObject、String、Int）、役割名詞を追加します。

流暢な使用法を目指す

• 文法的で読みやすい呼び出しサイトを生成するメソッド名を優先します。
• ファクトリメソッドは make で始めます。
• 副作用のない API を名詞句として、副作用のある API を命令形の動詞として名付けます。
• mutating/nonmutating の命名ペアの一貫性を保ちます（sort/sorted、formUnion/union）。
• ブール API は主張として読まれるべきです（isEmpty、intersects）。

用語をうまく使用する

• 精度が必要でない限り、専門用語より一般的な単語を優先します。
• 用語を使用する場合は、確立された意味を保持します。
• 非標準の略語を避けます。
• 共有の理解を改善する場合、確立されたドメイン先例を受け入れます。

慣例、パラメータ、およびラベル

• O(1) でない計算プロパティの複雑性を文書化します。
• 特殊な場合を除き、フリー関数よりメソッド/プロパティを優先します。
• 頭字語処理を含む Swift の大文字小文字の慣例に従います。
• 生成されたドキュメントの読みやすさを向上させるパラメータ名を使用します。
• セマンティクスが共有される場合、メソッドファミリーよりデフォルト引数を優先します。
• デフォルトパラメータを末尾の近くに配置します。
• スタイルの選好ではなく、文法と意味に基づいて引数ラベルを適用します。

特別な指示

• パブリック API サーフェスでタプルメンバーにラベルを付け、クロージャパラメータに名前を付けます。
• オーバーロードの曖昧性を避けるために、制約のないポリモーフィズムに明示的に対応します。
• ドキュメントコメントで示されたセマンティクスと名前を整合させます。

クイックリファレンス

名前パターン

状況	推奨パターン
Mutating 動詞	reverse()
Nonmutating 動詞	reversed() / strippingNewlines()
Nonmutating 名詞操作	union(_:)
Mutating 名詞操作	formUnion(_:)
ファクトリメソッド	makeWidget(...)
ブール問い合わせ	isEmpty, intersects(_:)

引数ラベルルール

状況	ルール
区別可能なラベルなし引数	区別が明確な場合のみラベルを削除します
値を保持する変換初期化子	最初のラベルを削除します
前置句の最初の引数	通常、前置詞からラベルを付けます
文法的フレーズの最初の引数	最初のラベルを削除します
デフォルト引数	ラベルを保持します（呼び出しサイトで削除される場合があります）
その他すべての引数	ラベルを付けます

ドキュメントルール

宣言種類	要約が説明すべき内容
関数/メソッド	それが何をするのか、何を返すのか
サブスクリプト	何にアクセスするのか
イニシャライザ	何を作成するのか
その他の宣言	それが何であるのか

レビューチェックリスト

明確性と流暢性

• 呼び出しサイトは実装の詳細を読まなくても明確です。
• 基本名には、曖昧性を取り除くのに必要なすべての単語が含まれています。
• 名前は簡潔で、型名の繰り返しを避けています。
• 呼び出しは自然に、そして最も重要な場所では文法的に読まれます。

命名セマンティクス

• 副作用のない API は名詞/問い合わせとして読まれます。
• 副作用のある API は命令形の動詞として読まれます。
• Mutating/nonmutating のペアは一貫した命名パターンを使用します。
• ブール API は主張として読まれます。

パラメータとラベル

• パラメータ名はドキュメントと役割の明確性を向上させます。
• デフォルトパラメータは一般的な使用法を簡潔にします。
• デフォルトパラメータは末尾の近くにあります。
• 最初の引数ラベルは文法と変換ルールに従います。
• 残りの引数は、削除が明確に正当化されない限りラベルが付けられます。

ドキュメントと慣例

• すべての宣言に有用な要約コメントがあります。
• 適切な場所でシンボルマークアップが使用されています。
• O(1) でない計算プロパティの複雑性が文書化されています。
• 大文字小文字と頭字語の大文字小文字は Swift の規範に従っています。
• オーバーロードは戻り値の型のみの区別や弱い型の曖昧性を避けます。

参考資料

• references/fundamentals.md - コア原則とドキュメントコメントルール
• references/promote-clear-usage.md - 曖昧性削減と役割ベースの命名
• references/strive-for-fluent-usage.md - 流暢性、副作用、および mutating ペア
• references/use-terminology-well.md - 用語、略語、および先例
• references/general-conventions.md - 複雑性ドキュメント、フリー関数例外、大文字小文字、オーバーロード
• references/parameters.md - パラメータ命名とデフォルト引数戦略
• references/argument-labels.md - 最初の引数とゼネラルラベルルール
• references/special-instructions.md - タプル/クロージャ命名と制約のないポリモーフィズム

哲学

• 宣言の巧妙さより、明確な使用サイトセマンティクスを優先します。
• ローカルスタイルルールを発明する前に、確立された Swift 慣例に従います。
• パブリック API サーフェスの保守性とレビューアビリティのために最適化します。
• ガイダンスを実用的に保ちます。明確性を改善する最小限の変更を適用します。