もくじ
どうもこんにちは。iOSをメインに開発しているロッキーカナイです。
本日はドキュメントコメントについて書いてみたいと思います。
開発は一人でする事もあるでしょうが、だいたい複数人で行うでしょう。
「ここのメソッドってどんな事やっているの？」という会話を耳にする事もしばしば。時間をかけて見ればメソッドの動作を把握できるでしょうが時間が勿体無いですね。
であれば初めから誰が見ても分かり易く、コメントを残すようにするべきだと常日頃から思っております。
そしてXcodeにはQuik Helpという、メソッドなどの機能や引数の説明をメモする機能がありますので、それを使ってコメントを残してみてはいかがでしょうか？
そもそもSwiftのコメントは通常のコメントと今回紹介するドキュメントコメントの２種類があります。
通常のコメント
/*
* 通常のコメント
*/
// 通常のコメントドキュメントコメント
/// ドキュメントコメントドキュメントコメントではMarkdown記法が使用でき、スタイル指定やリンクの設定も可能です。
メソッドにドキュメントコメントを追加してみました。
/// メソッド説明
/// - parameter num: 第１引数の説明
/// - parameter sum: 第２引数の説明
/// - returns: Bool 戻り値
func testMethod(_ num: Int, sum: Int) -> Bool {
return true
}上のドキュメントコメント時のQuik Helpの表示は以下の通りになります。
メソッド名をoption+クリックすると以下のようにも表示されます。
ドキュメントコメントには下記のようにもできます。
/// 説明
/// ***
/// ---
/// あいう
/// *サンプル*
/// **太文字**
/// [リンク](https://www.egao-inc.co.jp)が使用
/// # 大見出し
/// ## 中見出し
/// ### 見出し・***横線
・—横線
・斜体
・太文字
・リンク
・見出し
上のドキュメントコメント時のQuik Helpの表示は以下の通りになります。
メソッド名をoption+クリックすると以下のように表示されます。
今回はドキュメントコメントを紹介させて頂きました。
あなたが書いたコメントで、別のプログラマーの事故を防ぐという可能性だってあります。
コメントを残して、もっと見やすく、もっと事故の少ないコードを心がけていきましょう！
