「 コメント機能をうまく活用したい… 」
「 コメントってどう書くのが適切なの…? 」
プログラムに対してコメントを残すことで、コードが何をしているのか、なぜそれが必要なのか、あるいはある関数やメソッドがどのように動作するかを説明することができます。
コメントは、コードを書く人だけでなく、他の開発者がコードを理解するのを助けるためにも重要です。
本記事では、Xcodeにおける「コードコメントの基本的な使い方」をはじめ、「アノテーションコメント(MARK: など)」や、３つのスラッシュ「///」から始まる「ドキュメンテーションコメント」といった少し踏み込んだコメント機能の解説、さらにコメントを書く上でのアンチパターンについても触れていきます！
[ 本記事はこんな人におすすめ ]
・Xcodeでアプリ開発をしている
・コメント機能をさらに使いこなしたい
・コメントのアンチパターンについて知りたい
環境・バージョン
> Swift 5.7.2
> Xcode 14.2
> macOS 13.0 Ventura
Xcodeにおけるコメント機能の基本的な使い方をおさらいしておきます。
行単位のコメント
行単位のコメントを追加するには、コメントを追加したい行の先頭に「//」を入力します。
【記述方法】
// この行はコメント
複数行のコメント(ブロックコメント)
ブロックコメントを追加するには、コメントを追加したい部分を「 /*」 と 「*/」 で囲みます。
【記述方法】
/*
複数行のコメント
...
...
...
*/
「/*」を入力して[Return ↩︎]キーを押した時点で自動で語尾に「*/」が挿入され、ブロックが生成されます。
入力コードのコメントアウト
任意の行にカーソルを当てた状態で下記のショートカットを使うことで、コード行をコメントアウトすることができます。主にコードの一時的な退避などに用いられます。
【コメントアウトのショートカット】
Command⌘ + /
コメントアウトを解除するには、同じ行で再度ショートカットを実行します。
範囲選択することで複数行のコメントアウトも可能です。
アノテーションコメント
アノテーションコメントとは、特定のコード行に対して警告やエラー、またはその他の情報を提供するために使用される特殊コメントです。
アノテーションコメントには「MARK:」、「TODO:」、「FIXME:」のような特別なタグが含まれています。これらのタグは、Xcodeがコメントを自動的に認識し、ナビゲーターやミニマップに特殊な印を付与することができます。
アノテーションコメントには以下のような形式が用意されています。
// MARK: セクション見出し
// MARK: - ライン付きのセクション見出し
// TODO: 「後で○○しなければならない」の意味
// FIXME: 「○○を修正する必要がある」の意味
それぞれの機能を見ていきましょう。
MARKコメント
「MARKコメント」を使用すると、コード内にセクションを定義することができます。このセクションは、Xcodeのナビゲーターで見ることができ、コード内の異なるセクションを区別するのに役立ちます。
【記述方法】
// MARK: ここにセクション名を入力
以下のように、ナビゲーターにタグマーク付きの見出しが追加されます。
また、MARKコメントは以下のように「 – 」を付け足すことでセクションにラインを引くことができます。
【記述方法】
// MARK: - ライン付きのセクション見出し
また、MARKコメントはミニマップ上に拡大表示されます。
【ミニマップ表示切り替えのショートカット】
Command⌘ + Shift⇧ + Control ^ + M
TODOコメント
「TODOコメント」を使用すると、まだ完了していないタスクを記録することができます。
ナビゲーターにはリマインダーの絵文字で追加されます。
【記述方法】
// TODO: ここにタスクを入力
FIXMEコメント
「FIXMEコメント」を使用すると、修正する必要がある問題を記録しておくことができます。
ナビゲーターにはバンドエイドの絵文字で追加されます。
【記述方法】
// FIXME: 修正内容を入力
ドキュメンテーションコメント
ドキュメンテーションコメントを関数やクラス、プロパティなど任意の機能に追加することで、対象機能のドキュメントに解説を追加することができます。
以下の例では、メソッドに対してドキュメンテーションコメントを付与しています。コメントは３つのスラッシュ「///」から始まります。
/// この関数は、指定された文字列の最後に指定された文字列を追加します。
///
/// - Parameters:
/// - based: 元となる文字列
/// - suffix: 追加する文字列
///
/// - Returns: 新しい文字列
func appendString(_ based: String, suffix: String) -> String {
return based + suffix
}
対象機能のクイックドキュメントを開いてみると、コメント解説が追加されていることがわかります。ドキュメンテーションコメントが付与されていると、機能と目的が理解しやすいですね。
【クイックドキュメント表示ショートカット】
(任意の機能に対して)Option⌥ + クリック
-ドキュメンテーションコメント有り-
-ドキュメンテーションコメント無し-
ドキュメンテーションコメントのテンプレート挿入方法
Xcodeには、ドキュメンテーションコメントのパラメータを自動で検出して書き出してくれるテンプレート機能が備わっています。
以下の手順からテンプレート出力が可能です。
① コメント追加したい機能の行にカーソルを合わせておく
② 以下の手順でメニューバーから Editor > Structure > Add Documentation
を選択
以下のように、Xcodeが対象機能のパラメータを検出して、ドキュメンテーションコメントのテンプレートを自動生成してくれます。
これらのテンプレートはショートカットによる生成も可能です。
【ドキュメンテーションコメントのテンプレート生成ショートカット】
Command⌘ + Option⌥ + /
コメントのアンチパターンについて
コメントを残しておくことで読み手のコード理解を助けることができますが、何でもコメントを残しておけばいいというものではなく、コメントを書く上でいくつかのアンチパターンが存在します。
コメントのアンチパターンを避けるためには、コメントを書く前に、そのコメントが必要かどうか、どのような情報を伝えるべきか、コメントを読む人が理解しやすいかどうかを考えることが重要です。
以下の点に留意することで、コメントの質を向上させましょう。
アンチパターンとは
アンチパターン（Anti-pattern）とは、問題解決のために取られる手法やアプローチの中で、望ましくない効果や結果をもたらすものを指します。つまり、一見すると問題を解決するために選ばれる妥当な方法に見えるが、その実態は逆効果であるというパターンを指します。
1. 冗長なコメント
「冗長なコメント」とは、コード自体が意図を明確に示している場合に、余分な説明を加えることで、コードの読みやすさを損ねるコメントのことを指します。
例えば、次のようなコードを考えてみましょう。
// aとbを足して合計を計算します。
let total = a + b
この場合、「aとbを足して合計を計算します。」というコメントは、コード自体で意図を明確に示しているため、冗長であると言えます。
2. 説明不足のコメント
「説明不足のコメント」とは、コードの意図を明確に示すためのコメントが書かれていないか、またはコメントが不十分である場合に起こる問題です。
例えば、次のようなコードを考えてみましょう。
// 計算処理
let result = a * b
このコメントは、単に処理内容を簡単に説明しているだけで、計算結果がどのように使われるかについては何も説明されていません。加えて、変数aやbが何を示しているのかも不明です。これでは、コードの読み手に十分な情報を提供できていないため、コメントだけでなく、変数名にも改善の余地があるでしょう。
では、次のコード例だとどうでしょうか。
// 商品価格と個数を掛け合わせて、合計金額を計算します。
let totalPrice = productPrice * quantity
このコメントは、コードの意図を明確に示しています。productPriceとquantityを掛け合わせた結果を、totalPriceに代入することで、合計金額を計算していることが一目見て分かります。また、コメントが提供する情報は、コードだけでは分からない情報であるため、適切なコメントと言えます。
3. 間違ったコメント
「間違ったコメント」とは、コードの実際の動作と異なる説明を示すコメントのことを指します。
以下の例を見てみましょう。
// 5を3で割った結果を計算します。
let result = 5 / 3
このコメントは、実際のコードの動作と異なります。5を3で割った結果は1.6666…であり、整数型の変数に代入する場合には切り捨てが行われるため、結果は1となります。したがって、コメントが示す結果と、実際の結果が異なるため、このコメントは間違っています。
そのほかのパターンとして、「既存コードを変更したが、コメントの更新はしていなかった」といった場合にもこの問題は起こり得ます。コメントが最新のコードに対して補完できているかどうかにも注意が必要です。
4. コードの重要性を隠すコメント
「コードの重要性を隠すコメント」とは、コメントを使って、本来重要なコードの部分を隠すことを指します。
例えば、次のようなコードで考えてみます。
// この関数は、とても重要な処理を行います。
func deleteAllFunction() {
// ...
}
このコメントは、関数が非常に重要であることを伝えていますが、具体的に何をしているのかは明らかにされていません。このようなコメントは、重要な処理の実際の内容を隠し、読み手がコードを理解するのを妨げる可能性があります。
まとめ
以上、Xcodeにおけるコメント機能についてでした！
ポイントをおさらいしておきます。
- アノテーションコメントでナビゲートに適切な印を付与する
- ドキュメンテーションコメントで機能にドキュメント解説を追加する
- コメントを書く上でのアンチパターンに留意する
コードに対して最適なコメントを残すことができれば、開発者以外の人だけでなく、しばらく日が空いた後の開発者自身の助けにもなるでしょう。
本記事でご紹介したテクニックをぜひマスターして、コメントの質をレベルアップさせてください！
お役に立てば幸いです🙏
\ SHARE /
アプリ開発が学べる勉強会を開催中！
CodeCandyではアプリ開発を学ぶための勉強会を定期開催しています。
学習する習慣を身につけたい、他の参加者と作業したい、アプリ開発の基本をマスターしたい、という方のために無料で学べる勉強会です。
グループにメンバー登録して頂くと、イベント開催時にメールで通知されます。
グループのメンバーとして参加する徹底した基礎学習からマスターするiPhoneアプリ開発集中オンライン講座開講！
本書「iPhoneアプリ開発集中講座」を執筆している現役エンジニア講師陣が直接に指導！
基礎、課題実習で実践力を鍛えて、オリジナルアプリ公開までチャレンジ！
充実した転職支援もあるので、エンジニアへ転職したい人にもおすすめです！
まずは、現役エンジニアに相談できる無料相談をご利用ください。