コメント（// と /* */）

// 一行コメント — // から行末までがコメントになります。
let x = 10 // 行末コメント — コードの後にも書けます。

/* ブロックコメント — /* から */ までの範囲がコメントになります。
   Swift のブロックコメントは入れ子にできます。 */

/* 外側 /* 内側 */ 外側の続き — Swift ではこれが有効です */

/// 行ドキュメントコメント — 直後の宣言（関数・クラス・構造体等）を文書化します。
/// Markdown 記法が使えます。Xcode のクイックヘルプに表示されます。
func exampleFunction() {}

/** ブロックドキュメントコメント — /// と同じ役割です。
 * 複数行をまとめて書くことができます。
 * Xcode のクイックヘルプに表示されます。
 */
func blockDocFunction() {}

種類	書き方	概要
一行コメント	// テキスト	『//』から行末までがコメントになります。最も頻繁に使うコメントです。
ブロックコメント	/* テキスト */	複数行にまたがるコメントを書くときに使います。Swiftでは入れ子にできます。
行ドキュメントコメント	/// テキスト	直後の宣言を文書化します。Markdown記法に対応。Xcodeのクイックヘルプに表示されます。
ブロックドキュメントコメント	/** テキスト */	『///』のブロック版です。複数行をまとめて書くことができます。

Swiftのドキュメントコメントは標準のMarkdown記法に対応しています。また、Xcodeが解釈する特定のキーワード（『- Parameter』等）を使うことで、クイックヘルプのUI上で専用の表示領域に整形されます。

記法	概要
- Parameter 名前: 説明	関数の引数を説明します。引数ごとに1行書きます。
- Parameters: / - 名前: 説明	複数の引数をグループ化して書く別の書き方です。
- Returns: 説明	戻り値の型と内容を説明します。
- Throws: 説明	スローされる可能性のあるエラーを記述します。
- Note: テキスト	補足情報や注意事項を記述します。
- Warning: テキスト	警告事項を記述します。Xcodeで強調表示されます。
- Important: テキスト	重要な注意事項を記述します。
- Example: テキスト	使用例を記述します。
- SeeAlso: 参照先	関連する宣言や外部リソースへの参照を記述します。

判断	場面	理由
書くべき	「なぜこう実装したか」の理由	コードを読むだけではわからない設計意図やトレードオフを残しておくと、将来の自分や他の開発者が助かります。
書くべき	複雑なアルゴリズムや計算式	何をしているか一見でわかりにくい処理には、動作の概要を補足します。
書くべき	公開API（関数・クラス・構造体・プロトコル）	『///』でドキュメントコメントを付けるとXcodeのクイックヘルプやSwift-DocCのHTMLドキュメントに反映されます。
書くべき	デバッグ中の一時的な無効化	コメントアウトした理由や期限を残しておくと、後で削除し忘れるリスクが減ります。
書かなくてよい	コードを読めば明らかな処理	自明な説明はノイズになります。変数名・関数名をわかりやすくすれば不要になります。
書かなくてよい	変更履歴・削除したコード	バージョン管理（git）があるため、コメントに古いコードや変更日を残す必要はありません。

コメントの書き方（一行・ブロック・ドキュメントコメント）を確認するサンプルコードです。

comment_basic.swift

// comment_basic.swift — Swift のコメント構文の基本的な使い方です。

let items = ["widget", "gadget", "device"]
let prices = [1200, 3500, 800] // 税抜価格

/* 合計を計算して出力します */
let total = prices.reduce(0, +)

for (item, price) in zip(items, prices) {
    print(String(format: "%-10@ %5d yen", item, price))
}

print("----------")
print(String(format: "%-10@ %5d yen", "Total", total))

$ swift comment_basic.swift
widget      1200 yen
gadget      3500 yen
device       800 yen
----------
Total       5500 yen

comment_doc.swift

// comment_doc.swift — ドキュメントコメントを使って関数を文書化する例です。
// Xcode で Option+クリックするとクイックヘルプが表示されます。

/// 整数配列の平均値を計算して返します。
///
/// 配列が空の場合は `nil` を返します（クラッシュしません）。
///
/// - Parameter values: 平均を計算する整数の配列
/// - Returns: 平均値（`Double`）。配列が空の場合は `nil`。
///
/// ## Example
///
/// ```swift
/// let avg = calculateAverage([85, 92, 78, 95, 60])
/// print(avg!) // 82.0
/// ```
func calculateAverage(_ values: [Int]) -> Double? {
    guard !values.isEmpty else {
        // 空配列は計算不能なので nil を返します
        return nil
    }

    let sum = values.reduce(0, +)

    /* 整数除算を避けるために Double にキャストします */
    return Double(sum) / Double(values.count)
}

/** ブロックドキュメントコメントを使った別の書き方です。
 * /// と同じ内容をブロック形式で書けます。
 *
 * - Parameter value: 変換する整数値
 * - Returns: パーセンテージ文字列（例: "85%"）
 */
func formatPercent(_ value: Int) -> String {
    return "\(value)%"
}

// 動作確認
let scores = [85, 92, 78, 95, 60]

if let avg = calculateAverage(scores) {
    print("Average: \(avg)")
}

print(formatPercent(95))

// 空配列の場合
let empty: [Int] = []
print("Empty: \(calculateAverage(empty) as Any)")

$ swift comment_doc.swift
Average: 82.0
95%
Empty: nil

comment_nested.swift

// comment_nested.swift — Swift ではブロックコメントを入れ子にできます。

/* 外側のコメント
   /* 内側のコメント */
   外側の続き — Swift ではこれが有効です（C/C++ とは異なる）。
*/

let value = 42
print("value: \(value)")

$ swift comment_nested.swift
value: 42

Swiftのコメントは通常コメント（『//』『/* */』）とドキュメントコメント（『///』『/** */』）の2グループに分かれます。Swiftのブロックコメントはにネストに対応している点がC言語との違いで、既存のコメントを含むコードブロックをまとめてコメントアウトする場合に便利です。

ドキュメントコメント（『///』と『/** */』）はMarkdown記法に対応しており、『- Parameter』『- Returns』『- Throws』などのキーワードを使うとXcodeのクイックヘルプで整形された表示になります。Swift-DocCを使うとHTMLドキュメントを自動生成でき、Apple製フレームワークと同様のドキュメントサイトを構築できます。パブリックAPIには積極的にドキュメントコメントを付けておくと、Xcodeのコード補完時にも情報が表示されて利便性が高まります。