はじめに

Swift歴4ヶ月の新米プログラマーのメモ。

コメントの種類

Swiftにおけるコメントの書き方をざっくり分けると、以下の3つが挙げられる。

基本のコメント
アノテーションコメント
ドキュメンテーションコメント

基本のコメントは置いておいて、

アノテーション¹コメントとは、
プレフィックス²をつけてコメントの意図や状態を分かりやすくしたコメントのこと。
エディター上部のファイルパスバーに見出しをつけることもできる。

そして、ドキュメンテーションコメントは、
関数やクラスなどのドキュメントに解説をつけることができるコメントのこと。
一部Markdown記法をサポートしている。

1. 基本のコメント

単一行コメント

// 1行のコメント

コメントにしたい文字の前にスラッシュを2つ書くことで、その文字をコメントアウトすることができる。

ちなみに、「範囲選択 & cmd⌘ + /（Macの場合）」でコメントアウトのコマンドが使える。

複数行のコメント（ブロックコメント）

/*
 2行
 以上
 の
 コメント
 */

コメントにしたい文字の上下の行に、スラッシュとアスタリスクで文字をサンドするように書くことで、その文字をコメントアウトすることができる。

2. アノテーションコメント

TODOコメント

// TODO: タスクのコメント

未完了のタスクがある時に、そのタスクを記録するために使うアノテーションコメント。
単一行コメントの頭にTODO:と書くことで記録することができる。

FIXMEコメント

// FIXME: 修正箇所のコメント

修正の必要な問題がある時に、その問題の内容や修正箇所を記録するために使うアノテーションコメント。
単一行コメントの頭にFIXME:と書くことで記録することができる。

MARKコメント

// MARK: セクションのコメント

セクション³を作るために使うアノテーションコメント。ミニマップ内に拡大表示される。
単一行コメントの頭にMARK:と書くことで記録することができる。

// MARK: - ライン付きセクションのコメント

また、MARK:のあとにハイフンをつけると、ラインを引くこともできる。

？コメント

// ???: 不明箇所のコメント

よく分からない関数、調査が不十分なコードに対して、その旨を記録するために使うアノテーションコメント。
単一行コメントの頭に???:と書くことで記録することができる。

！コメント

// !!!: 要注意箇所のコメント

注意が必要なコードに対して、その旨を色苦するために使うアノテーションコメント。
単一行コメントの頭に!!!:と書くことで記録することができる。

3. ドキュメンテーションコメント

/// DocumentationCommentクラスの解説のコメント
class DocumentationComment() {

解説をつけたい関数やクラスの上の行にスラッシュを3つ書くことで、ドキュメントに解説をつけることができる。

ちなみに解説は、ドキュメントを開きたい関数やクラスの名前の上で「opt⌥ + クリック」
もしくは、エディターの右側、ユーティリティエリアのQuick Helpから見ることができる。

Markdownのサポート

/**
# 見出し1
##　見出し2
### 見出し3
#### 見出し4
##### 見出し5
###### 見出し6

- 箇条書きリスト
+ 箇条書きリスト
* 箇条書きリスト

1. 番号付きリスト
   1. ネストされた番号付きリスト

/// ```
/// コードブロック
/// ```

`コード`（エディター上は太字になるけど、ドキュメントは変わらない）

*強調*
_イタリック_

**太字**
__ボールド__

[リンク](https://swift.ui/)
  */

Playgroundのみ利用できるMarkdown記法もあるが、今回は省略

ドキュメンテーションテンプレート

Swiftには、関数やクラスからプロパティを自動で検出して、関数コメントをつけてくれる機能がある。

この機能は、関数コメントをつけたい関数やクラスの名前の上で、
メニューバーから Editor > Structure > Add Documentation
もしくは「opt⌥ + cmd⌘ + /」で呼び出すことができる。

関数コメント

ドキュメンテーションコメントには、Markupの指定文字が存在している。

コールアウト

/// - Attention: 注意のコールアウト

/// - Author: 著者のコールアウト（エディター上で太字にならない）
/// - Authors: 著者1
///   著者2
///   著者3

/// - Bug: バグのコールアウト

/// - Complexity: 複雑度のコールアウト

/// - Copyright: 著作権のコールアウト

/// - Date: 日時のコールアウト

/// - experiment: 実験のコールアウト（紫色）

/// - important: 重要のコールアウト（橙色）

/// - invariant: 不変条件のコールアウト

/// - Note: ノートのコールアウト

/// - Precondition: 前提条件のコールアウト

/// - Postcondition: 事後条件のコールアウト

/// - Remark: 備考のコールアウト

/// - Requires: 必要条件のコールアウト

/// - seealso: 参照のコールアウト

/// - Since: 以来（~から）のコールアウト

/// - Todo: タスクのコールアウト（エディター上で太字にならない）

/// - Version: バージョンのコールアウト

/// - Warning: 警告のコールアウト（赤色）

セクション

/// - Parameter param: パラメータのセクション
/// - Parameters:
///   - param1: パラメータ1
///   - param1: パラメータ2

/// - Returns: 戻り値のセクション

/// - Throws: 例外のコールアウト（見た目はコールアウト）

おわりに

頭で考えてたことって意外とすぐ忘れる。
覚えているうちに、コメントを残しておこう。

参考

アノテーション（annotation）とは、"注釈"という意味の英単語 ↩
プレフィックス（prefix）とは、"接頭辞"という意味を持つ英単語。 ↩
セクション（section）とは、"区分"という意味を持つ英単語。 ↩