swift-api-design-guidelines-skill

Swift API 設計ガイドライン スキル

概要

このスキルは、使用箇所で明確であり、呼び出し側で流暢に読め、確立された 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 は命令形の動詞として読める。
• 変更/非変更のペアは一貫した命名パターンを使用している。
• Boolean の API はアサーションとして読める。

パラメータとラベル

• パラメータ名がドキュメントと役割の明確さを向上させる。
• デフォルトパラメータが一般的な使用を簡素化する。
• デフォルト値を持つパラメータは末尾付近にある。
• 最初の引数のラベルが文法と変換のルールに従っている。
• 省略が明確に正当化されない限り、残りの引数にラベルが付いている。

ドキュメントと規約

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

リファレンス

• references/fundamentals.md - 中核となる原則とドキュメントコメントのルール
• references/promote-clear-usage.md - 曖昧さの低減と役割ベースの命名
• references/strive-for-fluent-usage.md - 流暢さ、副作用、変更ペア
• references/use-terminology-well.md - 専門用語、略語、前例
• references/general-conventions.md - 計算量のドキュメント、フリー関数の例外、大文字小文字、オーバーロード
• references/parameters.md - パラメータの命名とデフォルト引数の戦略
• references/argument-labels.md - 最初の引数と一般的なラベルのルール
• references/special-instructions.md - タプル/クロージャの命名と制約のないポリモーフィズム

哲学

• 宣言の巧妙さよりも、明確な使用箇所のセマンティクスを優先する。
• ローカルなスタイルルールを発明する前に、確立された Swift の規約に従う。
• 公開 API サーフェスの保守性とレビュー容易性のために最適化する。
• ガイダンスを実用的に保つ：明確さを向上させる最小の変更を適用する。