読み込み中...

Objective-Cのコメントの完璧な使い方10選

Objective-Cのプログラム中のコメントの正しい使い方を表すイラスト Objctive-C
2023.11.09
この記事は約17分で読めます。

【サイト内のコードはご自由に個人利用・商用利用いただけます】

この記事では、プログラムの基礎知識を前提に話を進めています。

説明のためのコードや、サンプルコードもありますので、もちろん初心者でも理解できるように表現してあります。

本記事のサンプルコードを活用して機能追加、目的を達成できるように作ってありますので、是非ご活用ください。

※この記事は、一般的にプロフェッショナルの指標とされる『実務経験10,000時間以上』を満たす現役のプログラマチームによって監修されています。

※Japanシーモアは、常に解説内容のわかりやすさや記事の品質に注力しております。不具合、分かりにくい説明や不適切な表現、動かないコードなど気になることがございましたら、記事の品質向上の為にお問い合わせフォームにてご共有いただけますと幸いです。
(送信された情報は、プライバシーポリシーのもと、厳正に取扱い、処分させていただきます。)

はじめに

Objective-Cは、iOSやmacOSなどのApple製品のアプリケーション開発に使用されるオブジェクト指向言語です。

本記事では、このObjective-Cでのコメントの使い方に関して、初心者から経験者まで、誰もが理解しやすいように10の具体的なサンプルコードとともに詳細に解説していきます。

コメントは、コードの理解を助けるためのものであり、効果的に使用することでコードの可読性や保守性が向上します。

この記事を通じて、Objective-Cのコメントの効果的な使い方をマスターしていただけることを期待しています。

●Objective-Cのコメントとは

コメントは、プログラムの中で実際の処理には関与しない部分であり、主にコードの説明や注意事項、TODOなどを記述するために使います。

これにより、他の開発者や未来の自分がコードを見返した際に、そのコードの動作や目的を迅速に理解できるようになります。

○コメントの基本的な役割と重要性

プログラムのソースコードは、マシンにとって解釈できる命令の集まりです。

しかし、人間にとってそのままのコードだけでは、何を目的としているのか、どのような処理の流れなのかを把握するのは難しい場合があります。

ここでコメントが役立ちます。

コメントを適切に使用することで、次のようなメリットが得られます。

  • コードの動作や目的を迅速に理解できる
  • コードの保守や修正が容易になる
  • チーム開発時におけるコミュニケーションツールとして利用できる

これらのメリットを実現するためには、ただコメントを書くだけではなく、そのコメントが適切であるかどうかが重要です。

適切なコメントとは、そのコードの目的や動作を正確に、かつ簡潔に表現するものを指します。

○シングルラインとマルチラインコメントの違い

Objective-Cには、2つの主なコメントの形式があります。

シングルラインコメントとマルチラインコメントです。

シングルラインコメントは、その名の通り1行のみのコメントを記述するためのものです。Objective-Cでは「//」を使用してシングルラインコメントを書くことができます。

このコメントは「//」の後に記述された行の終わりまでがコメントとして扱われます。

一方、マルチラインコメントは複数行にわたるコメントを記述するためのものです。

Objective-Cでは「/」でコメントを開始し、「/」でコメントを終了することでマルチラインコメントを書くことができます。

このコメントの中には何行でも記述することが可能です。

これらの違いを理解し、適切な場面で使い分けることが、コードの可読性を高める上で非常に重要です。

短い説明や一時的なメモにはシングルラインコメントを、長い説明や複数行にわたる注意事項にはマルチラインコメントを使用することが一般的です。

●Objective-Cコメントの使い方

Objective-C、一般的にiOSやmacOSのアプリケーション開発で使われる言語であり、コメントの書き方は他の多くのプログラミング言語と共通しています。

正確なコメントの記述は、コードの読解性を高め、開発者間のコミュニケーションを円滑にするために非常に重要です。

ここでは、Objective-Cでのコメントの基本的な使い方に焦点を当てて、具体的なサンプルコードとともにその使い方を解説します。

○サンプルコード1：基本的なシングルラインコメントの使い方

Objective-Cにおいて、シングルラインコメントは、コードの任意の部分に短い注釈や説明を追加するために使用されます。

具体的には、//を使用してその後の行の終わりまでの部分をコメントとして扱います。

int main() {
    // これはシングルラインコメントです
    NSLog(@"Hello, World!");
    return 0;
}

このコードでは、//を使ってシングルラインコメントを追加しています。

この例では、NSLog関数を使って文字列”Hello, World!”をコンソールに出力しています。

このコードを実行すると、コンソールに”Hello, World!”という文字列が出力されることを確認できます。

○サンプルコード2：マルチラインコメントの利用法

Objective-Cでは、複数行にわたるコメントを記述する際にマルチラインコメントを使用することができます。

具体的には、/* でコメントを開始し、 */ でコメントを終了します。

int main() {
    /*
    これはマルチラインコメントの例です。
    複数行にわたって説明や注釈を追加することができます。
    */
    NSLog(@"Hello, again!");
    return 0;
}

このコードでは、/*と*/を使ってマルチラインコメントを追加しています。

この例では、NSLog関数を使用して文字列”Hello, again!”をコンソールに出力しています。

このコードを実行すると、コンソールに”Hello, again!”という文字列が表示されることが確認できます。

○サンプルコード3：条件文内のコメントの置き方

Objective-Cの条件文の中にコメントを記述するとき、コードの読解性を高めるためには適切な位置にコメントを配置することが大切です。

ここでは、Objective-Cでの条件文内のコメントの置き方を表す例でを紹介します。

if (userAge >= 20) {
    // 成人と判断してアクセスを許可
    allowAccess();
} else {
    // 未成人と判断してアクセスを拒否
    denyAccess();
}

このコードでは、userAge変数の値に応じてアクセスを許可するか拒否するかを決定しています。

この例では、条件文の中に簡潔なコメントを配置して、各処理ブロックの目的を明確にしています。

実行後、20歳以上の場合、アクセスが許可され、それ以外の場合はアクセスが拒否されます。

○サンプルコード4：関数やメソッドに対するコメントの書き方

関数やメソッドの上部にコメントを記述することで、その関数やメソッドの役割、引数、戻り値などの情報を明示的に示すことができます。

このようなコメントは、特に他の開発者や未来の自分がコードを読む際に有効です。

ここでは、Objective-Cで関数に対するコメントの書き方を表す例を紹介します。

/**
 * 指定された二つの数値の合計を計算します。
 * @param num1 第一の数値
 * @param num2 第二の数値
 * @return 二つの数値の合計
 */
int addNumbers(int num1, int num2) {
    return num1 + num2;
}

このコードでは、addNumbers関数を使って二つの数値の合計を計算するコードを表しています。

この例では、関数の上部にドキュメンテーションコメントを使用して、関数の説明や引数、戻り値の情報を提供しています。

この関数をaddNumbers(3, 4);のように呼び出すと、結果として7が返されます。

コメントの記述方法はプロジェクトやチームによって異なることがありますので、一貫性を保つためにチーム内のルールやガイドラインに従うことが重要です。

○サンプルコード5：変数や定数の説明としてのコメントの使用法

プログラミングを行う上で、変数や定数の命名はとても重要です。

しかし、名前だけではその変数や定数が何のためのものなのか、どのような情報を保持しているのかを完全に伝えるのは難しいこともあります。

そのため、変数や定数の説明としてコメントを効果的に利用することが推奨されます。

// ユーザーの年齢を保持する変数
int userAge = 25;

// VAT (消費税) の定数値
const double VAT_RATE = 0.10;

このコードでは、userAgeという変数を使ってユーザーの年齢を保持するコードを表しています。

この例では、25歳のユーザーの年齢をuserAgeに代入しています。

また、VAT_RATEという名前の定数を使って消費税の定数値を表しています。

この例では、消費税率が10%であることを表しています。

変数や定数の前に適切なコメントを記述することで、他の開発者や未来の自分がコードを読む際に、その変数や定数の目的や意味を迅速に理解することができます。

○サンプルコード6：複雑なロジックの解説のためのコメントの例

プログラム内には、複雑なロジックやアルゴリズムが含まれることがあります。

そのような場面では、一目でコードの動きを理解するのが難しくなるため、詳細なコメントが求められます。

// 年齢に基づく特典の適用をチェックする関数
bool isEligibleForDiscount(int age) {
    // 13歳未満または65歳以上の場合、特典が適用される
    if (age < 13 || age >= 65) {
        return true;
    }
    return false;
}

このコードでは、isEligibleForDiscountという関数を使って年齢に基づく特典の適用をチェックするコードを表しています。

この例では、13歳未満または65歳以上の場合に特典が適用されるというビジネスロジックを実装しています。

○サンプルコード7：TODOやFIXMEを使用した開発中の注意点コメントの書き方

Objective-Cでの開発中、特定の部分がまだ完成していない、あるいは後で修正が必要な場面が出てきます。

このような場合、TODO や FIXME というキーワードを使ってコメントに記載することで、後で該当箇所を見つけやすくしたり、他の開発者に注意を促すことができます。

// TODO: メソッドの実装を完了させる
- (void)incompleteMethod {
    // 何らかのコード...
}

// FIXME: この関数のパフォーマンス問題を修正する
- (void)performanceIssueFunction {
    // パフォーマンスに問題があるコード...
}

このコードでは、TODO を使ってメソッドの実装がまだ完了していないことを示唆しています。

また、FIXME を使って、パフォーマンスの問題を後で修正する必要があることを明示しています。

このようにコメントを利用することで、開発中の注意点や修正が必要な箇所を可視化し、後の作業をスムーズに進める手助けとなります。

○サンプルコード8：警告や注意事項を含むコメントの記述方法

コードの中で、特定の部分に警告や注意事項を記載したい場面も出てくるでしょう。

Objective-Cにおいても、コメントをうまく活用することで、他の開発者や自分自身への注意を引きやすくすることができます。

// WARNING: この関数はデバッグモードでのみ使用すること！
- (void)debugOnlyFunction {
    // デバッグ専用のコード...
}

// NOTE: この変数は変更しないでください。システムの設定に影響します。
NSInteger systemSettingValue = 100;

このコードでは、WARNING というキーワードを使用して、ある関数がデバッグモードでのみ使用されるべきであることを表しています。

また、NOTE キーワードを使用して、特定の変数の変更を避けるように注意を促しています。

○サンプルコード9：関連するURLやリソースへのリンクを含むコメントの例

Objective-Cでのコメントは、コードに関連する外部リソースやドキュメントへのリンクを表す際にも役立ちます。

これにより、開発者や読者が追加情報を簡単に参照できるようになります。

しかし、URLは変わることがあるので、時折更新をする必要があります。

// この関数は以下の公式ドキュメントに基づいて実装されています。
// 参照：http://example.com/objective-c/documentation
void someFunction() {
    // 関数の実装部分
}

このコードでは、someFunctionという関数が公式ドキュメントに基づいて実装されていることを示すためのURLを含むコメントを表しています。

この例では、関数の定義の前にその関数の実装に関連する外部リソースへのURLを示しています。

実行後のコードを交えると、関数が適切に動作することが確認できますが、このサンプルコードの主目的はコメントのスタイルに関するものであるため、関数の実際の実行結果は省略します。

○サンプルコード10：その他、有効活用できるコメントのスタイルと方法

Objective-Cにおけるコメントは多岐にわたります。

ここではその他の有効なコメントのスタイルと使用方法の一例です。

// MARK: - 開始
// このマークは、特定のセクションや範囲を示すために使用されます。

// FIXME: この関数は期待する出力を返さない場合がある
void needsFixFunction() {
    // 関数の実装部分
}

// TODO: 将来的にデータベースから取得するように変更する
NSString *futureDatabaseValue = @"Initial Value";

このコードでは、複数の異なるコメントのスタイルを表しています。

具体的には、開始を表すMARK:、修正が必要な部分を表すFIXME:、将来の実装のためのメモとしてTODO:を用いたコメントを表しています。

この例では、コードの異なる部分やタスクに応じて異なるコメントのスタイルを使用して情報を整理しています。

●Objective-Cコメントの応用例

Objective-Cのコメントは、プログラムの振る舞いや目的を文書化するための有効なツールですが、高度な使用法も存在します。

コメントの応用例として、ドキュメンテーション生成ツールとの連携や、チーム開発時のコメントの共通ルールの定義などが考えられます。

これらの高度な使用法について、具体的なサンプルコードとその説明を通じて詳しく見ていきましょう。

○サンプルコード11：ドキュメンテーション生成ツールとコメントの連携例

Objective-Cの開発環境には、コメントから自動的にドキュメンテーションを生成するツールが存在します。

これにより、コード内のコメントをもとにAPIのリファレンスなどを簡単に作成することができます。

このコードでは、doxygenなどのツールを使用してドキュメンテーションを自動生成するためのコメントを表しています。

この例では、関数の概要や引数、戻り値に関する説明をコメントとして記述しています。

/**
 * @brief 与えられた2つの数値を加算する関数
 * @param num1 最初の数値
 * @param num2 2番目の数値
 * @return 2つの数値の合計
 */
int addTwoNumbers(int num1, int num2) {
    return num1 + num2;
}

上記のサンプルコードをdoxygenなどのツールで解析すると、関数の概要や引数、戻り値に関する情報がドキュメンテーションとして自動生成されます。

このようにして、コメントを効果的に活用することで、ドキュメントの作成作業を大幅に効率化することができます。

○サンプルコード12：チーム開発時のコメントの共通ルールと実例

チームでの開発を行う際、統一されたコメントの書き方やルールを定めることは非常に重要です。

これにより、チームメンバー間での情報共有がスムーズに行われ、コードの読みやすさや保守性が向上します。

このコードでは、チーム開発時におけるコメントの共通ルールとその実例を表しています。

この例では、変数の目的や使用理由、関数やメソッドの動作を詳しく説明するコメントの書き方を表しています。

// MARK: - Global Variables

// ユーザー情報を保持する辞書
NSDictionary *userInfo;

// MARK: - Initialization Methods

// ユーザー情報を初期化するメソッド
- (void)initializeUserInfo {
    userInfo = @{ @"name": @"John", @"age": @25 };
}

上記のサンプルコードでは、MARK:を使用してコードを明示的に区切る方法や、変数やメソッドの目的を明確にするコメントの書き方を採用しています。

このような共通のルールをチーム内で定めることで、コードの一貫性が保たれ、全体の品質向上に寄与します。

●Objective-Cのコメントの書き方の注意点と対処法

Objective-Cでの効果的なコメントの書き方は、コードの可読性と保守性を大幅に向上させることができます。

しかし、適切なコメントの使い方を理解していないと、逆にコードの理解を妨げる原因となることもあります。

ここでは、Objective-Cのコメントを書く際のいくつかの重要な注意点と、それに対する対処法を紹介します。

○過度なコメントの書きすぎに関する警告

コメントが多すぎると、コードの見通しが悪くなり、理解や保守が難しくなる可能性があります。

特に、自明なコードに対してのコメントは避けるべきです。

例えば、次のようなコードではコメントが冗長です。

// iを1増やす
i++;

この例では、i++; というコードは非常に明確であり、コメントは不要です。

コメントはコードの意図が自明でない場合、または複雑なロジックを説明する場合に限定することが望ましいです。

○コメントの更新とコードの一貫性の確保方法

コメントを書く際には、コードの変更に合わせてコメントも適宜更新する必要があります。

古いコメントが残っていると、コードの意図と異なる情報が伝わり、混乱を招く原因となります。

コードを更新する際には、関連するコメントも確認し、必要に応じて修正または削除を行います。

例えば、下記のコードで変数の目的が変更された場合、コメントも同時に更新する必要があります。

// ユーザーの年齢を格納
int age = 30;

このコードで、もしageがユーザーの年齢ではなく、勤続年数を意味するように変更された場合、コメントも適宜「ユーザーの勤続年数を格納」と修正する必要があります。

○マルチバイト文字を含むコメントの取り扱いと注意点

Objective-Cでは、UTF-8などのマルチバイト文字セットをサポートしていますが、環境によっては文字化けを引き起こす可能性があります。

特に、グローバルなプロジェクトや多言語環境での開発を行う場合、英語でのコメントを推奨します。

もし日本語などのマルチバイト文字を使用する必要がある場合は、ファイルの文字コードが正しく設定されていることを確認し、全ての開発者が同じ文字コードを使用していることを保証する必要があります。

また、日本語コメントを含むコードを他の環境に移植する際には、文字化けの可能性に注意し、必要に応じてテストを行うことが重要です。

●コメントのカスタマイズ方法

Objective-Cのコメントをさらに魅力的で可読性の高いものにするためには、IDE（統合開発環境）やテキストエディタのカスタマイズ機能を利用することが考えられます。

特に、色やスタイルを変更することで、コメントの可読性を向上させることができます。

○IDEやエディタでのコメントの色やスタイルの変更方法

多くのIDEやテキストエディタには、コメントの色やスタイルをカスタマイズする機能が搭載されています。

ここでは、人気のIDE「Xcode」を例に、コメントのカスタマイズ方法を解説します。

□Xcodeでのコメントの色変更

このコードではXcodeを起動して、メニューバーの「Xcode」→「Preferences」→「Fonts & Colors」を選択して、コメント部分の色を変更する方法を表しています。

具体的には、テーマ一覧から適切なテーマを選択し、右側のカラーパレットから「Comments」をクリックして色を変更します。

コメントの色を変更すると、特に大きなコードの中でコメントを探しやすくなるという利点があります。

例えば、重要なコメントやTODOコメントを目立たせるために、異なる色に設定するといったカスタマイズが可能です。

□Xcodeでのコメントのスタイル変更

Xcodeでは、コメントのフォントやサイズ、太さなどのスタイルも変更することができます。

具体的には、「Fonts & Colors」の設定画面で、コメント部分のフォントやサイズを調整することができます。

この例では、コメント部分を斜体にしたり、太字にすることで、他のコードとの区別をつけやすくする方法を表しています。

また、フォントサイズを大きくすることで、コメントの内容を一目で確認することができるようになります。

□その他のテキストエディタでのカスタマイズ

Xcode以外のテキストエディタ、例えば「Atom」や「Visual Studio Code」なども、様々なカスタマイズが可能です。

各エディタの設定やプラグイン、テーマを利用することで、Objective-Cのコメントを更に見やすくすることができます。

たとえば、Visual Studio Codeでは、拡張機能をインストールすることで、コメントのハイライトや色分け、スタイル変更などのカスタマイズを行うことができます。

まとめ

Objective-Cのコメントをより効果的に利用するためには、その基本的な使い方や様々なカスタマイズ方法を知ることが重要です。

コメントはコードの可読性を向上させるだけでなく、後々のメンテナンスや他の開発者との連携をスムーズにするための重要なツールとなります。

特にIDEやテキストエディタでのカラーやスタイルのカスタマイズは、コードの見やすさを一段と向上させることができます。

Objective-Cを使用するすべての開発者にとって、コメントの適切な使い方やカスタマイズ方法をマスターすることは、日々の開発作業をより効率的かつ効果的に進めるための鍵となるでしょう。