Blog | Swift.org Blog↗

Swift 3 のAPI設計ガイドライン

Swift 3 API Design Guidelines

Original: Swift 3 API Design Guidelines↗
Date: 2015.12.03
Authors
Category: Language

このダイジェストはClaude Opus 4.7 / 4.8によって生成されたものです（License）。原文はこちら↗。

この記事の要点

よく使われるライブラリの設計は、プログラミング言語全体の使い心地を大きく左右します。優れたライブラリは言語の延長のように感じられ、ライブラリ間で一貫性があるほど開発体験は良くなります。そこで Swift 3 の大きな目標の一つとして、API 設計ガイドラインを定め、それを一貫して適用する取り組みが進められています。
この取り組みは単なるドキュメントの整備にとどまらず、標準ライブラリの全面的な見直し、Objective-C API の Swift への取り込み方の改善、ガイドラインに沿っているかをコンパイラがチェックする仕組み、そして Swift 2 から Swift 3 へのマイグレータまで、複数の連動した作業から成り立っています。
これらの変更には source-breaking な（既存コードの修正を要する）ものが含まれますが、その分 Swift コード全体に統一感をもたらすことを狙ったものです。

背景: ライブラリ設計が言語全体の印象を決める

プログラミング言語の「感触」は、標準ライブラリやよく使われるフレームワークの設計に強く影響されます。ライブラリの API が言語そのものの延長のように自然であれば開発体験は良くなり、逆にライブラリごとに流儀がばらばらだと一貫性が損なわれます。

優れた Swift ライブラリを作りやすくするために、Swift 3 では API 設計ガイドラインを定義し、それを Swift の世界全体に一貫して適用していくことが目標とされました。

取り組みを構成する5つのピース

API 設計ガイドラインの策定は、互いに連動する複数の作業から成り立っています。

1. Swift API 設計ガイドライン本体

実際の指針となる Swift API Design Guidelines そのものの策定です。命名や引数ラベルの付け方など、Swift らしい API のあり方を文書化したもので、当時は活発に検討が進められていました。

2. 標準ライブラリの見直し

Swift 標準ライブラリ全体を、新しい API 設計ガイドラインに沿うよう見直し・更新する作業です。これにより標準ライブラリ自身がガイドラインの実例となります。

3. Objective-C API の取り込み方の改善

Apple プラットフォームでは、Cocoa / Cocoa Touch などの Objective-C API が Swift から利用されます。これらを Swift に取り込む際の変換ルールを改善し、Objective-C の API がより Swift の設計ガイドラインに馴染むようにします。

変換は一連のヒューリスティックによって自動的に行われ、その詳細は SE-0005（Objective-C APIのSwiftへの変換を改善する）にまとめられています。自動変換はヒューリスティックに基づくため、Cocoa / Cocoa Touch やそれを使う Swift コードへの影響を継続的に追跡し、うまく変換できない特定の API には NS_SWIFT_NAME のようなアノテーションを付けて結果を改善します。

この変更は主に Objective-C ランタイムを使う Apple プラットフォームに影響しますが、同じ API を提供するクロスプラットフォームの Swift core libraries にも波及します。

4. ガイドライン適合のチェック

既存の Swift コードは、Objective-C の Cocoa 向けコーディングガイドラインなど、さまざまなスタイルで書かれてきました。Objective-C API の取り込みに使うヒューリスティックを応用することで、Swift コンパイラが（任意で）ガイドラインに沿っていない API 設計パターンを検出し、改善案を提示できるようになります。

5. Swift 2 から Swift 3 へのマイグレータ

標準ライブラリの更新と Objective-C API の取り込み方の変更は、いずれも source-breaking な変更です。そのため、Swift 2 のコードを Swift 3 の API に合わせて更新するためのマイグレータが用意されます。