C言語の基本｜C言語のコメントの書き方

C言語の基本｜C言語のコメントの書き方

動くだけのコードから、意味まで伝わるコードへ。コメントを使って読みやすいプログラムを書こう。

これまでの学習では、printfを使って文字や整数を表示したり、scanfを使ってキーボードから値を受け取ったりしてきました。

プログラムが少しずつ長くなると、以前に自分で書いたコードを見て、この変数は何を表していたのだろう、この処理は何のために書いたのだろうと迷うことがあります。

そこで役立つのがコメントです。

コメントとは、ソースコードの中に書く説明文やメモのことです。コメントとして書かれた部分はプログラムの処理として実行されないため、動作を変えずにコードの意味や意図を残せます。

コメントは、特に次のような場面で役立ちます。

• プログラム全体の目的を説明する
• 変数に保存する値の意味を書く
• その処理を行う目的を残す
• scanfで入力する値や順番を示す
• 操作上の注意点を記録する
• 後からコードを読み返しやすくする

コメントを書かなくても、正しいC言語のコードであればプログラムは動きます。しかし、コメントがあると、コードの内容を短い時間で理解できるようになります。

他の人にとって読みやすいだけでなく、数日後や数か月後にコードを見直す自分にとっても、大切な手がかりになります。

コメントは人間に向けた説明文

C言語のソースコードには、コンピューターに処理を指示する部分と、人間が内容を理解するためのコメントを一緒に書けます。

たとえば、次の変数宣言だけを見ても、おおよその意味は分かります。

int reading_days;
int finished_pages;
int target_pages;

変数名の右側にコメントを追加すると、それぞれの変数へ何を保存するのかが、さらに分かりやすくなります。

int reading_days;     // 読書を続けた日数
int finished_pages;   // 読み終えたページ数
int target_pages;     // 今月の目標ページ数

コメントがあることで、英語の変数名にまだ慣れていなくても、変数の役割をすぐに確認できます。

コメントの代表的な役割は、次のとおりです。

コメントは、コンピューターを動かすための命令ではありません。ソースコードを読む人へ情報を伝えるための文章です。

図1：プログラムの処理とコメントの役割

この図から分かること

変数宣言、scanf、printfなどは、プログラムを動かすためのコードです。一方、コメントは、変数や処理の意味を人間に伝えるために使います。

コメントを書いても、scanfが受け取る値やprintfの表示結果は変わりません。動作を変えずに説明を追加できることが、コメントの大きな特徴です。

C言語で使用する2種類のコメント

C言語では、主に次の2種類のコメントを使用します。

短い説明には//、複数行にわたる説明には/* ... */を使うと、コードを整理しやすくなります。

//で始まる1行コメント

//を書くと、その位置から行末までがコメントになります。

行全体をコメントにする

行の先頭に//を書くと、その行全体をコメントとして扱えます。

// 読書記録を表示する
printf("今日の読書記録を表示します。\n");

1行目はコメントなので実行されません。2行目のprintfだけが実行されます。

処理のまとまりを説明するときは、次のようにコードの直前へコメントを書くと分かりやすくなります。

// 3つの整数をキーボードから受け取る
scanf("%d%d%d", &reading_days, &finished_pages, &target_pages);

このコメントを読むと、scanfで3つの整数を受け取ることがすぐに分かります。

コードの右側にコメントを書く

//は、C言語のコードを書いた後にも置けます。

int reading_days;     // 読書を続けた日数

この場合、int reading_days;は変数宣言として処理され、//より右側はコメントとして扱われます。

変数宣言の右側へ短い説明を書く方法は、変数の役割を示すときに便利です。

int reading_days;     // 読書を続けた日数
int finished_pages;   // 読み終えたページ数
int target_pages;     // 今月の目標ページ数

ただし、コメントが長すぎると1行が横に広がり、読みにくくなります。長い説明はコードの前に書くか、複数行コメントを利用しましょう。

1行コメントの主な使い方

//は手軽に使えるため、学習中の短いメモにも向いています。

/と/で囲む複数行コメント

説明が複数行にわたる場合は、/と/で囲むコメントを使用できます。

/* 読書日数、読み終えたページ数、
   今月の目標ページ数を入力する */
scanf("%d%d%d", &reading_days, &finished_pages, &target_pages);

/から始まり、/で終わるまでの範囲がコメントです。

1行だけをコメントにすることもできます。

/* 読書記録を表示する */
printf("今日の読書記録を表示します。\n");

複数行コメントは、次のような場面に向いています。

• プログラム全体について長めに説明する
• 複数の入力項目を順番に説明する
• 注意事項を複数行で残す
• 学習内容を少し詳しく記録する

たとえば、scanfで入力する順番を整理する場合は、次のように書けます。

/* 次の順番で整数を入力する
   1. 読書を続けた日数
   2. 読み終えたページ数
   3. 今月の目標ページ数 */
scanf("%d%d%d", &reading_days, &finished_pages, &target_pages);

説明を無理に1行へ詰め込まないため、入力順を確認しやすくなります。

複数行コメントは入れ子にできない

/* ... */を使うときに覚えておきたいのが、複数行コメントの中へ、別の複数行コメントを入れられないことです。

次のような書き方はできません。

/* 外側のコメント
   /* 内側のコメント */
   外側のコメントの続き
*/

この書き方では、最初に現れた*/でコメントが終了します。その後の部分はC言語のコードとして解釈されるため、コンパイルエラーの原因になります。

安全に使うため、次の点を覚えておきましょう。

• //は1行の説明に使う
• /* ... */は複数行の説明に使う
• /* ... /の中へ別の/ ... */を入れない
• /を書いたら、対応する/があるか確認する

普段は//を中心に使い、説明が長くなる場合だけ/* ... */を使うと整理しやすくなります。

図2：1行コメントと複数行コメントの使い分け

この図から分かること

//は、短い説明を書くときに便利です。変数の意味や処理の内容など、1行で伝えられるコメントに向いています。

/* ... */は、複数行にわたる説明を書くときに便利です。入力順や注意点など、1行では収まりにくい内容を整理できます。

どちらを使ってもコメントとしての役割は同じです。説明の長さや、コメントを置く場所に合わせて選びましょう。

コメントを使ったプログラムを作ってみよう

ここでは、キーボードから読書日数、読み終えたページ数、目標ページ数を入力し、その内容を表示します。

プログラム全体の目的、変数の意味、入力順が分かるようにコメントを付けています。

入力した整数から読書記録を表示するプログラム

ファイル名：3_8_1.c

// キー入力した整数から読書記録を表示するプログラム
#include <stdio.h>

int main(void)
{
    int reading_days;     // 読書を続けた日数
    int finished_pages;   // 読み終えたページ数
    int target_pages;     // 今月の目標ページ数

    // 読書日数、読んだページ数、目標ページ数の順に入力する
    scanf("%d%d%d", &reading_days, &finished_pages, &target_pages);

    printf("現在の読書記録を表示します。\n");
    printf("読書を%d日続けています。\n", reading_days);
    printf("これまでに%dページ読みました。\n", finished_pages);
    printf("今月の目標は%dページです。\n", target_pages);

    return 0;
}

実行結果の例

プログラムを実行すると、scanfによって入力待ちになります。次のように3つの整数を半角スペースで区切って入力し、Enterを押します。

入力例：

12 180 300

実行結果の例：

12 180 300
現在の読書記録を表示します。
読書を12日続けています。
これまでに180ページ読みました。
今月の目標は300ページです。

入力した12、180、300が、3つの変数へ順番に保存され、それぞれのprintfで表示されています。

コメントがあっても、入力や表示の動作には影響しません。

プログラム先頭のコメントを確認しよう

ファイルの先頭には、プログラム全体の目的を表すコメントがあります。

// キー入力した整数から読書記録を表示するプログラム

このコメントを読むだけで、ファイルにどのようなプログラムが書かれているかを把握できます。

プログラム先頭のコメントは、次のような場面で役立ちます。

• 練習用のソースファイルが増えたとき
• 過去に作成したプログラムを開いたとき
• 他の人へソースコードを見せるとき
• よく似た処理を持つファイルを区別するとき

プログラムの目的は、短く分かりやすく書くのがポイントです。

変数宣言の横にあるコメントを確認しよう

3つの変数には、それぞれ短いコメントが付いています。

int reading_days;     // 読書を続けた日数
int finished_pages;   // 読み終えたページ数
int target_pages;     // 今月の目標ページ数

変数名だけでもある程度は意味を予想できますが、日本語のコメントがあることで、その変数に何を保存するのかが明確になります。

たとえば、target_pagesという変数名だけでは、1日の目標なのか、1週間の目標なのかまでは分かりません。

int target_pages;     // 今月の目標ページ数

このようにコメントを付けると、対象となる期間まで正確に伝えられます。

ただし、分かりにくい変数名を付けても、コメントを書けば問題ないというわけではありません。最初に内容を想像しやすい変数名を付け、その意味をコメントで補うと、さらに読みやすくなります。

scanfの前にあるコメントを確認しよう

scanfの前には、入力する値と順番を説明するコメントがあります。

// 読書日数、読んだページ数、目標ページ数の順に入力する
scanf("%d%d%d", &reading_days, &finished_pages, &target_pages);

scanfで複数の値を入力するときは、入力順が重要です。

次のように入力した場合を考えてみましょう。

12 180 300

それぞれの値は、次の変数へ保存されます。

scanfは、入力された値の意味を判断して並べ替えるわけではありません。左から順番に、対応する変数へ保存します。

入力順をコメントに残しておけば、コードを確認するときに対応関係が分かりやすくなります。

読みやすいコメントを書くためのコツ

コメントは、数を増やせば必ず読みやすくなるわけではありません。内容が分かりやすく、現在のコードと一致していることが大切です。

処理の名前だけでなく目的を書く

次のコメントは、コードに書かれている関数名を繰り返しているだけです。

// scanfを実行する
scanf("%d%d%d", &reading_days, &finished_pages, &target_pages);

間違ったコメントではありませんが、コードを見ればscanfを使っていることは分かります。

次のように、何を入力するのかを書くと、より役に立つコメントになります。

// 読書日数、読んだページ数、目標ページ数を入力する
scanf("%d%d%d", &reading_days, &finished_pages, &target_pages);

コメントには、コードだけでは分かりにくい情報を補うと効果的です。

変数の意味は宣言した場所で説明する

変数についての説明は、宣言した場所の近くに書くと見つけやすくなります。

int reading_days;     // 読書を続けた日数

説明と変数が離れていると、どのコメントがどの変数を説明しているのか分かりにくくなります。

長い説明は複数行に分ける

長い説明を1行へ詰め込むと、画面を横へ移動しなければ読めなくなることがあります。

説明する内容が多い場合は、複数行コメントを利用できます。

/* 次の順番で整数を入力する
   1. 読書を続けた日数
   2. 読み終えたページ数
   3. 今月の目標ページ数 */
scanf("%d%d%d", &reading_days, &finished_pages, &target_pages);

内容が項目ごとに分かれているため、1行へまとめるより入力順を確認しやすくなります。

コードを変更したらコメントも変更する

コードとコメントの内容が食い違うと、コメントがない場合よりも混乱しやすくなります。

たとえば、変数の役割を今月の目標から今週の目標へ変更したとします。

int weekly_target;

このとき、以前のコメントを残してはいけません。

int weekly_target;    // 今月の目標ページ数

正しくは、コードに合わせてコメントも変更します。

int weekly_target;    // 今週の目標ページ数

ソースコードを修正したときは、周囲のコメントが新しい処理内容と一致しているか確認しましょう。

読めば分かる内容を繰り返しすぎない

次のコメントは、コードをそのまま日本語に置き換えたものです。

// 0を返す
return 0;

学習中にreturn 0;の意味を確認する目的で書くことはできます。しかし、すべての行へ同じようなコメントを付けると、かえってコードが読みにくくなる場合があります。

特に説明するとよいのは、次のような情報です。

• 変数が表しているもの
• 入力する値の意味や順番
• 処理を行う目的
• コードだけでは分かりにくい注意点

コメントの有無で実行結果は変わらない

コメントはプログラムとして実行されないため、コメントを追加したり削除したりしても、処理の内容が同じなら実行結果は変わりません。

コメントがあるコードは、次のようになります。

// 読書記録の見出しを表示する
printf("現在の読書記録を表示します。\n");

コメントを取り除くと、次のようになります。

printf("現在の読書記録を表示します。\n");

どちらも、画面には同じ内容が表示されます。

現在の読書記録を表示します。

コメントは実行結果を変えるためのものではなく、ソースコードの理解を助けるためのものです。

学習中にコメントを書きたい場所

C言語を学び始めた段階では、特に次の3か所へコメントを書くと効果的です。

この3か所にコメントがあるだけでも、プログラム全体の見通しがよくなります。

慣れてきたら、処理のまとまりや注意点などにも、必要に応じてコメントを追加してみましょう。

図3：読みやすいコメントを置く3つの場所

この図から分かること

ファイルの先頭にはプログラム全体の目的、変数宣言の横には変数の意味、scanfの前には入力する内容や順番を書くと、コードの役割を追いやすくなります。

ただし、プログラムを修正したときは、コメントも一緒に見直す必要があります。古い説明を残さず、現在のコードと一致したコメントを保つことが大切です。

printfの練習プログラムにコメントを追加しよう

2つ目のプログラムでは、printfで予定を表示する短いコードにコメントを加えます。

プログラム全体の目的と、各printfが何を表示しているのかが分かるようにしています。

運動予定をコメント付きで表示するプログラム

ファイル名：3_8_2.c

// 今日の運動予定を表示するプログラム
#include <stdio.h>

int main(void)
{
    // ウォーキングを行う時間を表示する
    printf("今日は%d分ウォーキングします。\n", 25);

    // ストレッチを行う回数を表示する
    printf("ストレッチを%d回行います。\n", 5);

    return 0;
}

実行結果の例

今日は25分ウォーキングします。
ストレッチを5回行います。

プログラム内には3つのコメントがありますが、実行結果には表示されていません。

ファイル先頭のコメントは、プログラム全体の目的を表しています。

// 今日の運動予定を表示するプログラム

1つ目のprintfの前には、表示内容を説明するコメントがあります。

// ウォーキングを行う時間を表示する
printf("今日は%d分ウォーキングします。\n", 25);

2つ目のprintfの前にも、同じように処理内容が書かれています。

// ストレッチを行う回数を表示する
printf("ストレッチを%d回行います。\n", 5);

コメントを削除してもprintfの動作は変わりません。しかし、コメントがあると、コードを上から読んだときに各処理の目的を確認しやすくなります。

練習するときは、表示する数値や文章を変更するだけでなく、コメントも新しい内容に合わせて変更してみましょう。

Windowsのパスで使用するバックスラッシュ

Windowsのコマンド操作では、ファイルやディレクトリーの場所を表すために、バックスラッシュ\を使用します。日本語環境では、画面上で円記号に見えることがあります。

パスは、ファイルやディレクトリーの場所を示す住所のようなものです。

バックスラッシュは、ディレクトリーの階層を区切るために使われます。

たとえば、現在使用しているドライブのルートにあるchap03へ移動する場合は、次のように指定します。

cd \chap03

cworkの中にあるchap03へ移動する場合は、次のように指定します。

cd \cwork\chap03

2つの指定先は異なります。

今回のファイルをC:\cwork\chap03へ保存した場合は、コマンドプロンプトで次のように移動できます。

cd \cwork\chap03

その後、GCCで3_8_1.cをコンパイルします。

gcc -std=c17 3_8_1.c -o 3_8_1

各部分の意味は次のとおりです。

コンパイル後は、次のように実行します。

3_8_1

バックスラッシュはC言語のコメント記号ではありません。Windowsのパスではディレクトリーの区切りとして使われ、C言語のソースコードでは//や/* ... */がコメントを表します。

コードを書いたら、まずはファイルの目的、変数の意味、入力内容の3か所へ短いコメントを加えてみましょう。コメントを自分の言葉で書くことによって、プログラムの処理を整理する練習にもなります。