🖥️
【C言語超入門】第17回コメント

2024/12/25に公開
入門
C言語
tech
https://youtu.be/D7pRpunLnrA


\textcolor{pink}{四国めたん: }教師役ですわ


\textcolor{lime}{ずんだもん: }生徒役なのだ
\footnotesize \textcolor{pink}{四国めたん:} 皆さん、こんにちは。四国めたんです
\footnotesize \textcolor{lime}{ずんだもん:} ずんだもんなのだ。こんにちはなのだ
\footnotesize \textcolor{pink}{四国めたん:} 今回もC言語のお勉強をしていきましょう
\footnotesize \textcolor{lime}{ずんだもん:} レッツゴーなのだ
\footnotesize \textcolor{pink}{四国めたん:} 前回は 関数 の作成についてお話ししましたわ
\footnotesize \textcolor{lime}{ずんだもん:} おぼえているのだ
\footnotesize \textcolor{pink}{四国めたん:} そして 関数 を作成する際には、 関数 の機能が判るような関数名を付けることが推奨されますわ
\footnotesize \textcolor{lime}{ずんだもん:} 後々、プログラムの確認が容易になるのだ
\footnotesize \textcolor{pink}{四国めたん:} とはいえ 関数 の機能を説明するために、長すぎる関数名とするのは、お勧めできませんわ
\footnotesize \textcolor{lime}{ずんだもん:}  関数 を呼び出す側も大変なことになるのだ
\footnotesize \textcolor{pink}{四国めたん:} そんな時に便利なのが コメント ですわ
\footnotesize \textcolor{lime}{ずんだもん:}  コメント ？
\footnotesize \textcolor{pink}{四国めたん:} はい、 コメント を使えば、プログラムに影響を与えずに、説明などを付け加えることができますわ
\footnotesize \textcolor{lime}{ずんだもん:} お～、 関数 の機能の説明に便利なのだ
\footnotesize \textcolor{pink}{四国めたん:} 特に最近では コメント に日本語を使うこともできる場合が多いので、更に便利になりましたわ

 コメントの挿入方法は2種類です\footnotesize \textcolor{pink}{四国めたん:}  コメント を挿入する方法は2つですわ
\footnotesize \textcolor{lime}{ずんだもん:} 2つもあるのか？
\footnotesize \textcolor{pink}{四国めたん:} はい、ひとつは 1行コメント で、もうひとつは 複数行コメント ですわ
\footnotesize \textcolor{lime}{ずんだもん:} 詳しく教えてほしいのだ
\footnotesize \textcolor{pink}{四国めたん:} わかりましたわ

 1行コメントはお手軽ですよ\footnotesize \textcolor{pink}{四国めたん:} まずは 1行コメント ですわね
\footnotesize \textcolor{lime}{ずんだもん:} どのように書けばいいのだ？
\footnotesize \textcolor{pink}{四国めたん:} ダブルスラッシュ"//"の後にコメントを記述しますわ
\footnotesize \textcolor{lime}{ずんだもん:}  1行コメント というからには、ダブルスラッシュ"//"から行末までがコメントとなるのか？
\footnotesize \textcolor{pink}{四国めたん:} その通りですわ
新しいコメントの書き方ですもともとのC言語では、ダブルスラッシュ"//"を使ったコメントは許されていませんでした
ただ、後のC++などの言語では、ダブルスラッシュ"//"を使ったコメントが一般的になりました
それを受けて、C99というC言語の規格でダブルスラッシュ"//"を使ったコメントが導入されたました
\footnotesize \textcolor{pink}{四国めたん:} まずは、前回の関数のプログラム例にコメントを付けて実行してみましょう
#include <stdio.h>

// a + bを計算する関数です。
int add(int a, int b) {
  int c = a + b;
  return c;
}

void main() {
  int x = 1;
  int y = 2;
  int z = add(x, y);  // 足し算の関数を呼び出します。
  printf("xとyの和は%dです\n", z);
}
\footnotesize \textcolor{lime}{ずんだもん:} 特に変わりはないのだ
\footnotesize \textcolor{pink}{四国めたん:} コメントがプログラムに影響を与えていないことが確認できましたわ
\footnotesize \textcolor{lime}{ずんだもん:} ところでダブルスラッシュ"//"は行の先頭ではなくてもいいのか？
\footnotesize \textcolor{pink}{四国めたん:} はい、コードの最後に追加する形でもOKですわ

 複数行コメントは便利です\footnotesize \textcolor{pink}{四国めたん:} もう1つは 複数行コメント ですわ
\footnotesize \textcolor{lime}{ずんだもん:}  1行コメント と違って、複数行にわたってコメントを書けるのか？
\footnotesize \textcolor{pink}{四国めたん:} その通りですわ
\footnotesize \textcolor{lime}{ずんだもん:} どのように書けばいいのだ？
\footnotesize \textcolor{pink}{四国めたん:} スラッシュ-アスタリスク"/*"とアスタリスク-スラッシュ"*/"の間にコメントを記述しますわ
\footnotesize \textcolor{lime}{ずんだもん:} スラッシュ-アスタリスク"/*"とアスタリスク-スラッシュ"*/"の間なら複数行にわたるコメントもOKなのか？
\footnotesize \textcolor{pink}{四国めたん:} その通りですわ
\footnotesize \textcolor{pink}{四国めたん:} とりあえず、関数のプログラム例にコメントを付けて実行してみましょう
#include <stdio.h>

/* a + bを計算する関数です。
   aとbは整数です。
   整数の値が返ります。 */
int add(int a, int b) {
  int c = a + b;
  return c;
}

void main() {
  int x = 1;
  int y = 2;
  int z = add(x, y); /* 足し算の関数を呼び出します。 */
  printf("xとyの和は%dです\n", z);
}
\footnotesize \textcolor{lime}{ずんだもん:} こちらも特に変わりはないのだ
\footnotesize \textcolor{pink}{四国めたん:} はい、コメントがプログラムに影響を与えていないことが確認できましたわ
\footnotesize \textcolor{lime}{ずんだもん:} ところでスラッシュ-アスタリスク"/*"も行の先頭ではなくてもOKなのだな
\footnotesize \textcolor{pink}{四国めたん:} そうですわね

 コメントはどこでも入れられる？\footnotesize \textcolor{pink}{四国めたん:} いままで コメント は基本的にプログラムに影響しないと言ってきましたわ
\footnotesize \textcolor{lime}{ずんだもん:} そうなのだ
\footnotesize \textcolor{pink}{四国めたん:} ただし挿入できない場所はありますわ
\footnotesize \textcolor{pink}{四国めたん:} また、コメントを推奨される場所もありますわね
\footnotesize \textcolor{lime}{ずんだもん:} 詳しく教えてほしいのだ
\footnotesize \textcolor{pink}{四国めたん:} わかりましたわ

 こんな場所はコメントを入れられません\footnotesize \textcolor{pink}{四国めたん:} まず、基本的にダブルスラッシュ"//"によるコメントは、行末にいれますわ
\footnotesize \textcolor{lime}{ずんだもん:} 1行を全てコメントにする場合もダブルスラッシュ"//"を使えるのだ
\footnotesize \textcolor{pink}{四国めたん:} 対して"/*  */"によるコメントは、殆どの場所に入れられますわ
\footnotesize \textcolor{lime}{ずんだもん:} 具体的にはどんな感じなのだ
\footnotesize \textcolor{pink}{四国めたん:} 例えば数式の途中でも入れることは可能ですわ
\footnotesize \textcolor{pink}{四国めたん:} とりあえず例を見てみましょう
#include <stdio.h>

int add(int a, int b) {
  int c = /* 数式の途中でもコメントできます */ a + b;
  return c;
}

void main() {
  int x = 1;
  int y = 2;
  int z = add(x, /* 関数コールの途中でもコメントできます */ y);
  printf("xとyの和は%dです\n", z);
}
\footnotesize \textcolor{lime}{ずんだもん:} 数式の途中や関数の引数の前にコメントが入っているのだ
\footnotesize \textcolor{pink}{四国めたん:} はい、でもダブルクォート等で囲われた文字列の途中にはコメントを入れられませんわ
\footnotesize \textcolor{pink}{四国めたん:} 他にも、文字の指定の途中や変数名、関数名等の途中ではコメントを入れられませんわね
\footnotesize \textcolor{lime}{ずんだもん:} いろいろと制限があるのだ
\footnotesize \textcolor{pink}{四国めたん:} 試しに関数名の途中にコメントを入れてみましょう
#include <stdio.h>

int ad/* 関数名や変数名の途中ではコメントできません */d(int a, int b) {
  int c = a + b;
  return c;
}

void main() {
  int x = 1;
  int y = 2;
  int z = add(x, y);
  printf("xとyの和は%dです\n", z);
}
\footnotesize \textcolor{lime}{ずんだもん:} 「E0065  ;  が必要です」というエラーになったのだ

 こんな場所はコメントを入れましょう\footnotesize \textcolor{pink}{四国めたん:} 基本的にコメントを入れる、入れないは好みの問題ですわ
\footnotesize \textcolor{lime}{ずんだもん:} え～、結構、いいかげんなのだ
\footnotesize \textcolor{pink}{四国めたん:} とはいえ、コメントを入れる方がいい場所もありますわ
\footnotesize \textcolor{lime}{ずんだもん:} どのようなコメントを入れればいいのか、教えてほしいのだ
\footnotesize \textcolor{pink}{四国めたん:} まずは「関数の説明のためのコメント」ですわ
\footnotesize \textcolor{lime}{ずんだもん:} ふむふむ
\footnotesize \textcolor{pink}{四国めたん:} 次に「ファイルの説明のためのコメント」ですわね
\footnotesize \textcolor{lime}{ずんだもん:} なるほどなのだ
\footnotesize \textcolor{pink}{四国めたん:} とりあえずは、それぞれについて詳しくお話ししますわ
\footnotesize \textcolor{lime}{ずんだもん:} よろしくなのだ

 関数の説明のためのコメントは必須です\footnotesize \textcolor{pink}{四国めたん:} まず、関数についての説明は、コメントとして書いておいた方がいいですわ
\footnotesize \textcolor{lime}{ずんだもん:} べつに関数名が適切ならば、コメントなんか無くてもいいのではないのか？
\footnotesize \textcolor{pink}{四国めたん:} 関数名だけでは内容が不十分ですし、後から読み直すと、結構、忘れているものですわ
\footnotesize \textcolor{lime}{ずんだもん:} なるほどなのだ
\footnotesize \textcolor{lime}{ずんだもん:} ところで、コメントにはどのようなことを書けばいいのだ？
\footnotesize \textcolor{pink}{四国めたん:} 関数の機能については必須ですわね
\footnotesize \textcolor{pink}{四国めたん:} そのほかには引数に渡す値や戻り値についての説明は書いた方がいいですわ
\footnotesize \textcolor{lime}{ずんだもん:} りょうかいなのだ
\footnotesize \textcolor{lime}{ずんだもん:} ちなみに関数については、定義と宣言があったのだ
\footnotesize \textcolor{lime}{ずんだもん:} コメントは両方に同じものを書けばいいのか？
\footnotesize \textcolor{pink}{四国めたん:} いえ、関数の宣言がある場合には、そちらにのみコメントを付ければOKですわ
\footnotesize \textcolor{pink}{四国めたん:} とりあえず関数のプログラム例にコメントを付けてみます
#include <stdio.h>

/* a + bを計算する関数です。
   aとbは整数です。
   整数の値が返ります。 */
int add(int a, int b);

void main() {
  int x = 1;
  int y = 2;
  int z = add(x, y);
  printf("xとyの和は%dです\n", z);
}

int add(int a, int b) {
  int c = a + b;
  return c;
}
\footnotesize \textcolor{pink}{四国めたん:} ちなみにVisual Studioでは、関数名の上にカーソルを持って行くことでコメントを表示してくれますわ
\footnotesize \textcolor{lime}{ずんだもん:} お～、べんりなのだ

 ファイルの説明のためのコメントも必要ですよ\footnotesize \textcolor{pink}{四国めたん:} ファイルの説明のためのコメントも書いた方がいいですわ
\footnotesize \textcolor{pink}{四国めたん:} 特に他人に見られる可能性のあるファイルやヘッダーファイルにはコメントは必要ですわね
\footnotesize \textcolor{lime}{ずんだもん:} ヘッダーファイル？
\footnotesize \textcolor{pink}{四国めたん:} 後の章で解説する予定ですわ
\footnotesize \textcolor{lime}{ずんだもん:} まっているのだ
\footnotesize \textcolor{lime}{ずんだもん:} ところでファイルの説明のためのコメントは、どのようなことを書けばいいのだ？
\footnotesize \textcolor{pink}{四国めたん:} ファイル内に、どのような関数があるかやライセンスについての注記などを記載しますわ
\footnotesize \textcolor{pink}{四国めたん:} 例としては、こんな感じですわね
/*

ファイル全体の説明等を最初に記述

作者: ファイル作成者の名前

バージョン: できれば変更毎にバージョンを記述

ライセンス: ライセンス情報(GPL, BSD, Apache, MITなど)

*/

 コメントは適度に書くのが重要です\footnotesize \textcolor{lime}{ずんだもん:} ところでコメントは、いっぱい書いておけばいいのか？
\footnotesize \textcolor{pink}{四国めたん:} いえ、コメントは適度に書くのが重要ですわ
\footnotesize \textcolor{lime}{ずんだもん:} どの程度がいいのだ？
\footnotesize \textcolor{pink}{四国めたん:} 例えば、処理の途中には特にコメントを付ける必要はないと思いますわ
\footnotesize \textcolor{lime}{ずんだもん:} なぜなのだ？
\footnotesize \textcolor{pink}{四国めたん:} 何を行っているかはプログラムを読めば判りますわ
\footnotesize \textcolor{pink}{四国めたん:} そのような場合は、コメントはかえってプログラムを読みにくくしてしまいますわ
\footnotesize \textcolor{lime}{ずんだもん:} それでも処理に関するコメントが必要な場合はどうするのだ？
\footnotesize \textcolor{pink}{四国めたん:} そのような場合には、関数のコメントに書く方が判り易いと思いますわ
\footnotesize \textcolor{lime}{ずんだもん:} りょうかいなのだ

 コメントアウトは便利です\footnotesize \textcolor{pink}{四国めたん:} ここでひとつ、便利なテクニックをお教えしますわ
\footnotesize \textcolor{lime}{ずんだもん:} どのようなテクニックなのだ？
\footnotesize \textcolor{pink}{四国めたん:}  コメントアウト という、コメントの機能を使ったプログラミングテクニックですわ
\footnotesize \textcolor{pink}{四国めたん:} 例えばプログラミング中に、今とは異なる処理方法を試したくなった場合などに使うと便利ですわね
\footnotesize \textcolor{lime}{ずんだもん:} どのように行えばいいのだ？
\footnotesize \textcolor{pink}{四国めたん:} まず、既に書いてあるプログラムを １行コメント や 複数行コメント でコメントにしておきますわ
\footnotesize \textcolor{pink}{四国めたん:} 続いて新しいプログラムを付け足しますわ
\footnotesize \textcolor{lime}{ずんだもん:} そうすると何かいいことがあるのか？
\footnotesize \textcolor{pink}{四国めたん:} はい、元に戻したくなったときに、戻すのが簡単になりますわ
\footnotesize \textcolor{lime}{ずんだもん:} たしかに、既に書いたプログラムを消してしまったら、元に戻したくなったときには書き直しが面倒なのだ
\footnotesize \textcolor{pink}{四国めたん:} 例として、足し算の関数で、足した後に2倍にする処理を試す場合を考えてみましょう
#include <stdio.h>

int add(int a, int b) {
  //int c = a + b;
  int c = 2 * (a + b);
  return c;
}

void main() {
  int x = 1;
  int y = 2;
  int z = add(x, y);
  printf("xとyの和は%dです\n", z);
}
\footnotesize \textcolor{lime}{ずんだもん:} たしかに、これなら足し算のみのコードに戻すのも簡単なのだ
\footnotesize \textcolor{pink}{四国めたん:} ちなみにVisual Studioでコメントアウトを解除する場合には、コメント行を選択して\fcolorbox{blue}{lightgray}{Ctrl}-\fcolorbox{blue}{lightgray}{k} \fcolorbox{blue}{lightgray}{Ctrl}-\fcolorbox{blue}{lightgray}{u}を押せば選択行を解除できますわね
\footnotesize \textcolor{pink}{四国めたん:} さらにコメントアウトする行を選択して\fcolorbox{blue}{lightgray}{Ctrl}-\fcolorbox{blue}{lightgray}{k} \fcolorbox{blue}{lightgray}{Ctrl}-\fcolorbox{blue}{lightgray}{c}を押せば選択行をコメントアウトできますわ
\footnotesize \textcolor{lime}{ずんだもん:} お～、便利なのだ
ドキュメンテーションジェネレータコメントにまつわる話題としては ドキュメンテーションジェネレータ があります
読んで字のごとくプログラムからドキュメントを自動的に作成してくれる機能もしくはアプリです
有名どころとしては以下の3つでしょうか
Javadoc
Doxygen
Sphinx
Visual Studioではデフォルトとして XMLドキュメント の形式を採用しています
個人的にはドキュメンテーションジェネレータとしてDoxygenを推奨します
XMLドキュメントの形式もサポートしていますので、Visual Studioでは使い易いと思います

 JavadocJavaのプログラムからHTML形式のドキュメントを生成してくれます
/**  */(スターが2つになっている事に注意)の形式のコメント内にアットマーク@で始まるタグを埋め込むことで一定の形式でドキュメントを作成できます

 Doxygen汎用のドキュメンテーションジェネレータでC言語やC++、Java、Python、C#等にも対応しています
HTML以外にもPDFやLaTex、PostScript等も出力できます
単体のアプリケーションのため様々な開発環境で使用できるところも利点と云えます
基本的にはJavadocと同様に/**  */(スターが2つになっている事に注意)の形式のコメント内にアットマーク@で始まるタグを埋め込むことで一定の形式でドキュメントを作成できます
他のコメントの形式やタグを表す記号も使用できますので、かなり自由度が高いです

 SphinxPythonで書かれたドキュメンテーションジェネレータですが、Python以外の言語にも対応しています
HTMLの他、PDFの出力等にも対応しています

 XMLドキュメント純粋なドキュメントジェネレータではないのですが、コメントにXMLタグを用いたドキュメントを書くことで一定の形式でドキュメントを作成できます
Visual Studioでは XMLドキュメント 形式のコメントがデフォルトとなっています
C#等ではドキュメントジェネレータとしてDocFxを用いてドキュメントの生成が可能です
Doxygenでもドキュメントの生成が可能です
なおコメントはトリプルスラッシュ///により開始します。
例えば関数addの上の行にトリプルスラッシュ///を入力すると必要なXMLタグが自動的に挿入されます
#include <stdio.h>
/// <summary>
///
/// </summary>
/// <param name="a"></param>
/// <param name="b"></param>
/// <returns></returns>
int add(int a, int b) {
  int c = a + b;
  return c;
}

void main() {
  int x = 1;
  int y = 2;
  int z = add(x, y);
  printf("xとyの和は%dです\n", z);
}
特に関数のコメント入力が非常に楽になりますので上手に使いましょう

 まとめ\footnotesize \textcolor{pink}{四国めたん:} お疲れさまでした
\footnotesize \textcolor{lime}{ずんだもん:} おつかれさまなのだ
\footnotesize \textcolor{pink}{四国めたん:}  コメント についての説明は以上ですわ
\footnotesize \textcolor{lime}{ずんだもん:} 意外とコメントを入れる場所が難しかったのだ
\footnotesize \textcolor{pink}{四国めたん:} コメントの内容や入れる場所については、最初はあまり気にしないで、自由に書いていいと思いますわ
\footnotesize \textcolor{lime}{ずんだもん:} そんなんでいいのか？
\footnotesize \textcolor{pink}{四国めたん:} はい、経験を積めば、よりよいコメントを書けるようになりますわ