swift-api-design-guidelines

Swift API 設計ガイドライン

Swift API 設計ガイドラインを適用し、命名、ラベル、ドキュメント、呼び出し箇所の明確さを整えます。複合的なリクエストでは、API 設計に関する部分をここで扱い、言語や型システムに関する作業は swift-language に、並行処理は swift-concurrency に、Lint の設定は swiftlint に振り分けます。

目次

• 引数ラベルのルール
• 副作用に関する命名
• 変更型と非変更型のペア
• ドキュメントコメント
• 明確さと命名
• 流暢な使用法とプロトコル
• 一般的な規約
• よくある間違い
• レビュー用チェックリスト
• 参考資料

引数ラベルのルール

引数ラベルによって、呼び出し箇所での読みやすさが決まります。最初に当てはまる行のルールを適用します。

状況	ルール	例
最初の引数が文法上の句を完成させる	ラベルを省略し、単語をベース名に組み込む	addSubview(y)
値を保持する初期化変換	最初のラベルを省略する	Int64(someUInt32)
引数が区別のない同等の値である	すべてのラベルを省略する	min(x, y)
最初の引数が前置詞句を完成させる	前置詞をラベルにする	fade(from: red)
最初の2つの引数が1つの抽象概念を成す	前置詞をベース名に組み込む	moveTo(x: b, y: c)
その他すべて	ラベルを付ける	split(maxSplits: 2)

抽象概念の境界、複数の前置詞、変換イニシャライザー、区別のない同等の値、パラメーターの命名、デフォルト引数を判断する際は、引数ラベルとパラメーターを参照してください。

副作用に関する命名

副作用のある操作には命令形の動詞を、副作用のない操作には結果を表す名詞句または形容詞句を、Boolean API にはアサーション形式の名前を使用します。

array.sort()
array.append(newElement)
let d = point.distance(to: origin)
line.isEmpty
set.contains(element)

純粋操作と変更操作のペアの詳しい例や、Boolean の命名を確認する際は、副作用と変更型のペアを参照してください。

変更型と非変更型のペア

変更型と非変更型のペアには、操作を自然に表す名前を付けます。

• 動詞による操作では、変更型には命令形を、コピーには結果を表す分詞を使用します。例：sort()/sorted() または append(_:)/appending(_:)。-ed を優先し、-ed が文法的に不自然な場合、または返される結果ではなく直接目的語を表す場合に限り、-ing を使用します。
• 名詞による操作では、コピーには名詞を、変更型には form + 名詞を使用します。例：union(_:) / formUnion(_:)。
• 新しい値を作成するファクトリーには make を接頭辞として付けます。

返される結果を表す文法が明確でない場合は、-ed/-ing の判断フローチャートを参照してください。同じ資料に、form 接頭辞、Boolean、ファクトリーのパターンも詳しく記載されています。

ドキュメントコメント

すべての公開宣言にドキュメントコメントを付ける必要があります。

宣言の種類ごとの要約ルール

宣言	要約で説明する内容
関数 / メソッド	何を行い、何を返すか
サブスクリプト	何にアクセスするか
イニシャライザー	何を作成するか
型 / プロパティ / 変数	それが何であるか

要約は動作を表す場合は動詞から、対象を表す場合は名詞句から始まる、1つの文の断片として記述し、末尾にピリオドを付けます。

/// Returns the element at the specified index.
func element(at index: Int) -> Element { ... }

/// The number of elements in the collection.
var count: Int { ... }

/// Creates a new array with the given elements.
init(_ elements: some Sequence<Element>) { ... }

/// Accesses the element at the specified position.
subscript(index: Int) -> Element { ... }

シンボルのマークアップ

必要に応じて、要約の後に標準のシンボルマークアップを使用します。

• 個々のパラメーターには - Parameter name:
• 複数のパラメーターには - Parameters: ブロック
• 戻り値には - Returns:
• スローされるエラーには - Throws:
• アルゴリズムの計算量には - Complexity:

/// Removes and returns the element at the specified position.
///
/// - Parameter index: The position of the element to remove.
/// - Returns: The removed element.
/// - Complexity: O(*n*), where *n* is the length of the collection.
mutating func remove(at index: Int) -> Element { ... }

O(1) 計算量のルール

O(1) ではない計算プロパティの計算量は必ず文書化してください。呼び出し側は、プロパティがデフォルトで O(1) であると想定します。プロパティが定数時間を超える処理を行う場合は、計算量を明示してください。

/// The total weight of all items.
///
/// - Complexity: O(*n*), where *n* is the number of items.
var totalWeight: Double {
    items.reduce(0) { $0 + $1.weight }
}

ドキュメントのパターンと例については、references/conventions-and-special-rules.md を参照してください。

明確さと命名

使用箇所における明確さが最も重要な目標です。すべての設計上の決定は、呼び出し箇所を読む人のためにあります。

簡潔さよりも明確さ。 曖昧さを取り除けるのであれば、より長い名前を使用してもかまいません。略語は使用しないでください。

// GOOD
employees.remove(at: position)

// BAD — ambiguous: remove the element? remove at position?
employees.remove(position)

曖昧さを避けるために必要な語を含めてください。 ある語を省略すると呼び出し箇所が不明確になる場合は、その語を残してください。

// GOOD — "at" clarifies the argument's role
friends.remove(at: index)

// BAD — is "index" the element to remove or the position?
friends.remove(index)

不要な語は省略してください。 コンテキストからすでに得られる型情報を繰り返さないでください。

// GOOD
allViews.remove(cancelButton)

// BAD — "Element" repeats the type
allViews.removeElement(cancelButton)

変数とパラメータは型ではなく役割で命名してください。 型名ではなく、現在のコンテキストにおけるそのエンティティの役割を使用してください。

// GOOD — describes the role
var greeting: String
func add(_ observer: NSObject, for keyPath: String)

// BAD — names the type
var string: String
func add(_ object: NSObject, for string: String)

弱い型情報を補ってください。 パラメータの型が Any、AnyObject、または Int や String のような基本型である場合は、役割を明確にする語を名前に追加してください。

// GOOD — role is clear despite weak types
func addObserver(_ observer: NSObject, forKeyPath path: String)

// BAD — what does "string" mean here?
func add(_ object: NSObject, for string: String)

命名のさらなる例とパターンについては、references/naming-and-clarity.md を参照してください。

流暢な使用とプロトコル

呼び出し箇所は文法的な英語として読めるようにします。 使用箇所で文法的なフレーズを形成する名前を優先してください。

// GOOD — reads fluently
x.insert(y, at: z)          // "x, insert y at z"
x.subviews.remove(at: i)    // "x's subviews, remove at i"
x.makeIterator()             // "x, make iterator"

// BAD — ungrammatical
x.insert(y, position: z)
x.subviews.remove(i)

イニシャライザの最初の引数。 イニシャライザの最初の引数は、型名を継続するフレーズを形成してはいけません。

// GOOD
let foreground = Color(red: 32, green: 64, blue: 128)

// BAD — "Color with red" reads awkwardly
let foreground = Color(havingRGBValuesRed: 32, green: 64, blue: 128)

プロトコルの命名規則:

プロトコルが表すもの	命名パターン	例
何かがであるもの	名詞	Collection、IteratorProtocol
能力	-able、-ible、または -ing 接尾辞	Equatable、Hashable、Sendable

一般的な規則

大文字と小文字の使い分け。 型とプロトコルは UpperCamelCase を使用します。それ以外はすべて lowerCamelCase を使用します。アメリカ英語で一般にすべて大文字になる頭字語は、位置に応じて一貫して大文字または小文字で表記します。

var utf8Bytes: [UTF8.CodeUnit]
var isRepresentableAsASCII = true
var userSMTPServer: SMTPServer

自由関数よりもメソッドとプロパティ。 メソッドとプロパティを優先してください。自由関数は次の場合にのみ使用します:

1. 明らかな self が存在しない — min(x, y)
2. その関数が制約のないジェネリックである — print(value)
3. その関数の構文が確立されたドメイン記法である — sin(x)

メソッドファミリーよりもデフォルト引数。 受け入れるパラメータだけが異なるメソッドのファミリーよりも、デフォルトパラメータを持つ単一のメソッドを優先してください。デフォルト値を持つパラメータは末尾に配置します。デフォルト値を持つパラメータには常に引数ラベルを付けるべきです。デフォルトパラメータは通常呼び出し箇所で省略されるため、実際に現れるときにはそのラベルが明確でなければなりません。

// GOOD — labeled with defaults
func decode(_ data: Data, encoding: String.Encoding = .utf8) -> String?

// BAD — method family
func decode(_ data: Data) -> String?
func decode(_ data: Data, encoding: String.Encoding) -> String?

オーバーロードの安全性。 メソッドは、異なる型ドメインで動作する場合、またはその意味がコンテキストから明確である場合に、基底名を共有してもかまいません。呼び出し箇所で曖昧さを引き起こす、戻り値の型だけが異なるオーバーロードは避けてください。

大文字と小文字の使い分けのエッジケース、オーバーロードのパターン、タプルやクロージャの命名については、references/conventions-and-special-rules.md を参照してください。

よくある間違い

間違い	修正
曖昧または欠落したラベル	remove(at:) のように、呼び出しが文法的に読めるようにします。
誤った mutating/nonmutating の形式	変更には命令形の動詞を、コピーには文法的な -ed/-ing または名詞形を使用します。
名前が型や実装を説明している	役割と意味的な効果を命名します。
パブリック API に目的や計算量のドキュメントがない	簡潔な概要を追加し、O(1) でないプロパティを文書化します。
form またはファクトリ接頭辞が誤って適用されている	form は名詞の操作のために確保し、ファクトリには make を使用します。
型情報が繰り返されている	宣言とコンテキストからすでに明確な語を削除します。
オーバーロードが戻り値の型だけ異なる	意味のある名前またはパラメータの区別を追加します。
タプルやクロージャの構成要素が位置ベースである	パブリックな構成要素とクロージャのパラメータにラベルを付けます。

レビューチェックリスト

引数ラベル

• 最初の引数が適切なラベル規則（文法的な句、前置詞句、変換、またはラベル付き）に従っている
• 前置詞句のラベルで、独立した引数を誤ってまとめていない
• 値を保持する変換のイニシャライザーでは、最初のラベルを省略している
• 特別なケースに該当しないすべての引数にラベルがある

命名の意味

• 変更を加えるメソッドでは命令形の動詞を使用している
• 変更を加えないメソッドでは -ed/-ing 形または名詞形を使用している
• 変更を加えるメソッドと加えないメソッドのペアが、適切なパターン（動詞のペア、または名詞形／形式名詞のペア）に従っている
• 真偽値プロパティがアサーションとして読める（isEmpty、isValid、contains）
• 変数とパラメーターは型ではなく役割に基づいて命名している

ドキュメント

• すべての公開宣言にドキュメントコメントがある
• 要約はピリオドで終わる単一の文断片になっている
• 要約が宣言の種類に応じた適切な内容（動作、アクセス、生成、実体）を説明している
• O(1) ではない計算プロパティについて、計算量を記載している
• パラメーター、戻り値、スローされるエラーがシンボルマークアップを用いて記載されている

規約

• 型とプロトコルには UpperCamelCase を、それ以外には lowerCamelCase を使用している
• 略語の大文字・小文字の表記が、位置に応じて統一されている
• メソッド群よりもデフォルト引数を優先している
• オーバーロードが戻り値の型だけで異なることはない
• プロトコル名が、名詞（is-a）または接尾辞（能力）の規約に従っている

参考資料

• 命名の明確さ、役割に基づく命名、弱い型付けの補完、用語について：references/naming-and-clarity.md
• 引数ラベルの例外ケース、パラメーターの命名、デフォルト引数の方針について：references/argument-labels-and-parameters.md
• 副作用に関する命名例、-ed/-ing の判断ツリー、form- 接頭辞のパターン、ファクトリーメソッドについて：references/side-effects-and-mutating-pairs.md
• 大文字・小文字表記の例外ケース、計算量の記載、オーバーロードの安全性、タプル／クロージャーの命名、グローバル関数の例外について：references/conventions-and-special-rules.md