0Pricing
Swift Academy · レッスン

スタイルガイドとAPI設計ガイドライン

明確な 名前 、考え抜いた 引数ラベル 、適切な デフォルト値 、簡潔な ドキュメントコメント を使って、使いやすいSwift APIを設計します。

「スタイルガイドとAPI設計ガイドライン」はCoddyKit上の無料Swift Academyレッスンです。 これはレッスン2/3です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはSwift Academy学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 Swift Academyコースには全3レッスンが含まれています。

原則

優れたAPIは読みやすく、予測しやすく、小さくまとまっています。

  • 意図を説明する名前
  • 役立つ引数ラベル
  • 一般的なケース向けのデフォルト値
  • 簡潔なドキュメントと例

命名の基本

アクション => 動詞、データ => 名詞とします。意味が分かりにくくなる略語は避けてください。

// Prefer clear, simple names.
// BAD:
func doCalc(_ a: Int, _ b: Int) -> Int { a + b }

// GOOD:
func sum(_ a: Int, _ b: Int) -> Int { a + b }

// BAD (ambiguous):
struct Cfg { let v: Int }
// GOOD (nouns for data types):
struct Configuration { let retries: Int }

print(sum(2, 3))  // 5

引数ラベル

ラベルがあると、呼び出し側を自然に読めます：remove(at:)、insert(_:at:)。

// Choose labels that explain a parameter's role.
// BAD:
func remove(_ index: Int) { print("remove", index) }

// BETTER:
func remove(at index: Int) { print("remove at", index) }

// Mixed labels:
func insert(_ item: String, at index: Int) {
    print("insert", item, "at", index)
}

remove(at: 2)
insert("a", at: 1)

適切なデフォルト

一般的な呼び出しを短くしながら柔軟性も保つには、デフォルト引数を使います。

// Provide defaults to cover the 80% case.
func greet(_ name: String, times: Int = 1, shout: Bool = false) {
    let msg = shout ? "HELLO, \\(name)!" : "Hello, \\(name)!"
    for _ in 0..<times { print(msg) }
}

greet("Ana")                 // default: once, not shouting
greet("Ben", times: 2)
greet("Cara", shout: true)

副作用と可変性

副作用を明示します。状態を変更するメソッドにはmutatingを使い、適切な場合はprivate(set)で読み取り専用のビューを公開してください。

// Prefer pure functions when possible; name mutating effects explicitly.
struct Counter {
    private(set) var value = 0
    mutating func increment(by amount: Int = 1) { value += amount }
}

var c = Counter()
c.increment()
c.increment(by: 3)
print("value =", c.value) // 4

APIのドキュメント化

ドキュメントコメントのヒント：

  • 1文の要約から始めます。
  • どのように動くかではなく、何をするかを説明します。
  • 小さな呼び出し例を示します。
  • 重要な場合にだけ、前提条件やパフォーマンス上の注意点を記載します。

ラベルを使う理由

確認問題：外部ラベルはいつ追加すべきですか？

まとめ

まとめ：明確な名前を優先し、読みやすいラベルを追加し、一般的な呼び出しにはデフォルト値を用意し、副作用を明示して、例を添えた簡潔なドキュメントを作成します。

よくある質問

「スタイルガイドとAPI設計ガイドライン」レッスンは無料ですか？

はい。「スタイルガイドとAPI設計ガイドライン」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、Swift Academyコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 Swift Academyコースには全3レッスンが含まれています。

「スタイルガイドとAPI設計ガイドライン」で何を学びますか？

明確な 名前 、考え抜いた 引数ラベル 、適切な デフォルト値 、簡潔な ドキュメントコメント を使って、使いやすいSwift APIを設計します。 ブラウザで直接実行するハンズオンコードでSwift Academyを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

Swift Academyを始めるのに経験は必要ですか？

事前経験は必要ありません。CoddyKitのSwift Academyは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン2/3です。

「スタイルガイドとAPI設計ガイドライン」レッスンにはどのくらい時間がかかりますか？

ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

このSwift Academyレッスンでコードを書いて実行できますか？

はい。すべてのSwift Academyレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

このコースのすべてのレッスン

  1. SwiftFormat／SwiftLintの基礎
  2. スタイルガイドとAPI設計ガイドライン
  3. コードのドキュメント化（DocC入門）
← Swift Academyに戻る