プログラミング入門8.スクールでは絶対に教えてくれないコメントの書き方

こんちゃっす、ダイブツです！

今回はプログラムの処理とは関係無いですが、地味に大事なコメントの書き方について説明していきますね。

プログラミングを続けていくと、あなたは今後、こんな状況に出くわします。

・プログラムを他人に見せても内容を理解されない
・久しぶりに自分が書いたプログラムを読んでも、内容の理解に時間がかかる

こんな状況をぶっ壊すのに役立つのが今回学習するコメントなんです。

もし、あなたが今後仕事でコメントを書いても困らないように、0から100まで、搾りカスすらも出てこないぐらい全力な内容をこれから伝えていきます。

単純なのに効果がバカでかいコメントの使い道

まず、「あなたがコメントって何？」と思っているかもしれないので、コメントとは何かを説明しておきますね。

コメント(またはコメントアウト)とは、書いてある文字を無視すること、ただそれだけです。

単純ですよね？

だから、本当だったらプログラム中に書けない日本語もコメントだったら書けるっていうメリットがあります。

そして、このコメントの役割っていうのが、大きく分けて3つあります。

それが、

・一時的に処理を止める

・昔の処理を残しておく

・プログラムの説明を記載する(重要)

です。

この3つの内容について、後程詳しく説明していきます。

まずはコメントの書き方から見ていきましょう。

たった2文字だけでできるコメントの書き方

プログラム中にコメントを書くのって本当に簡単です。

なんてったって最小2文字で書けるんですからね。

ただ、コメントは1行のみに効果が出るものと、複数行まとめて効果が出るものの2種類あります。

どっちも使う頻度は多いので、ここで覚えときましょう！簡単ですしね。

書き方を説明するのに使う元のコードはこれにします。
青色の四角形を表示するだけのとっっっても簡単なコードです。

size(600,400);

fill(0,0,255);
rect(50,50,200,200);

1行コメントの書き方

1行コメントの書き方は本当に簡単です。

四角形を青色に設定する処理をコメントアウトしたい場合は、「//」を書きます。

これだけで四角形を青色に塗る処理が省略されて、白い四角形が表示されるようになります。

size(600,400);

//fill(0,0,255);
rect(50,50,200,200);

複数行コメントの書き方

複数行コメントの書き方もいたって簡単です。

「/*」と「*/」で省略したい内容を囲んであげればいいだけです。

今回の例だったら、四角形を書く処理を省略したので、何も描画されないウィンドウが表示されるようになりますよ。

size(600,400);
/*
fill(0,0,255);
rect(50,50,200,200);
*/

あとこの複数行コメントの書き方は、1行と言わず、本当に一部分の箇所だけコメントアウトすることもできます。

例えばこんな書き方ですね。

size(600,400);

fill(0,0,255 /* ←これは青色の指定だよ！ */);
rect(50,50,200,200);

ただ、この書き方はプログラム変更する時の邪魔にもなりかねないので、あまり使わない方がいいです。

もしこんなプログラムを見かけたとしても驚かないように仕様だけ知っておきましょう。

プログラミング言語の仕様って、こんな風にあまり使わない書き方でも書けちゃったりしますからね・・・。

でもこういう細かい仕様を知っている方がスキルは高くなりますよ。

じゃあ、コメントの書き方もわかったことですし、肝心の使い道の方を見ていきましょうか！

使い道1：一時的に処理を止める

この使い道が、よくプログラミングスクールとか、プログラミング学習サイトで言われている内容です。

もう↑で説明したコメントの書き方の内容と同じですね。

「ちっと動き気に入らなかったから変えてみっかな～」ぐらいの軽い気持ちで書くのが。この使い道にあたります。

でもコメントの力ってそんなもんじゃないんです。

それを次から説明していきます。

使い道2：昔の処理を残しておく

これは仕事でよく使う方法です。

この使い道は何かっていうのを、以前の講座で使ったプログラムを例に説明しましょう。

⇒このプログラムを説明している講座はこちら

まず、四角形を6つ表示させる元のプログラムがあります。

size(600,400);

int iRectSize = 50;
int iRectPosX = 20;
final int RECT_X_NUM = 6;
final int RECT_INTERVAL = 100;

for(int i = 1; i <= RECT_X_NUM; i++){
  rect(iRectPosX,20,iRectSize,iRectSize);
  iRectPosX = iRectPosX + RECT_INTERVAL;
}

で、このプログラムを次のように全然違う処理に変更することになりました。

この時にコメントを使わずに全てプログラムを書き換えると次のようになりますね？

size(600,400);

int iRectSizeX = 500;
int iRectSizeY = 300;
int iRectPosX = 20;
int iRectPosY = 20;
final int RECT_NUM = 5;
final int RECT_INTERVAL = 30;

for(int i = 1; i <= RECT_NUM; i++){
    rect(iRectPosX,iRectPosY,iRectSizeX,iRectSizeY);
  
  iRectPosX = iRectPosX + RECT_INTERVAL;
  iRectPosY = iRectPosY + RECT_INTERVAL;
  
  iRectSizeX = iRectSizeX - (2 * RECT_INTERVAL);
  iRectSizeY = iRectSizeY - (2 * RECT_INTERVAL);
}

ただ、仕事だと「やっぱやーめた、前の処理に戻そ！」ということを言われることが頻繁にあるんですよ。（マジで！）

そんな時に元のプログラムを残していないと、また同じプログラムを作成することになって時間が無駄にかかるんですね。

これが↓のように元の処理がコメントで残っていたらどうですか？

たった2行（今までの処理をコメントアウトするのを含めると4行）修正するだけで無駄な作業が減るんですよ？！

これは絶対にやるべきですよね？

size(600,400);

/*   2017/10/21に○○さんが消せって言うから仕方なく・・・仕方なく消す処理だよ？！
int iRectSize = 50;
int iRectPosX = 20;
final int RECT_X_NUM = 6;
final int RECT_INTERVAL = 100;

for(int i = 1; i <= RECT_X_NUM; i++){
  rect(iRectPosX,20,iRectSize,iRectSize);
  iRectPosX = iRectPosX + RECT_INTERVAL;
}
*/

int iRectSizeX = 500;
int iRectSizeY = 300;
int iRectPosX = 20;
int iRectPosY = 20;
final int RECT_NUM = 5;
final int RECT_INTERVAL = 30;

for(int i = 1; i <= RECT_NUM; i++){
    rect(iRectPosX,iRectPosY,iRectSizeX,iRectSizeY);
  
  iRectPosX = iRectPosX + RECT_INTERVAL;
  iRectPosY = iRectPosY + RECT_INTERVAL;
  
  iRectSizeX = iRectSizeX - (2 * RECT_INTERVAL);
  iRectSizeY = iRectSizeY - (2 * RECT_INTERVAL);
}

で、これで修正してからまた数日後には「やっぱりまた前の処理に・・・」って話がくるんですよ、よくある話ですｗ

自分の作業時間を減らす為に必要なコメントの使い道なんですね。

ただ1つ注意しなきゃいけないのが、なんでもかんでもコメントアウトして元の処理を残しておくと、プログラムが半端なく読みにくくなります。

なので、コメントで元のプログラムを残しておく場合は、関数丸ごと等、区切りが分かりやすい単位で残しておくようにしましょう。

さらに、変更が入りそうな箇所だけに絞って元のプログラムを残せるようになると、もっとプログラムが読みやすくなりますよ！

使い道3：プログラムの説明を記載する(重要)

さぁこれが一番大事なコメントの使い道です。

仕事で絶対に使う内容なのに何故か全然プログラミングスクールや学習サイトで教えていないんですよね～、ホント不思議です。

それで、コメントでプログラムの説明を記載するっていうのは、本当にそのままの意味です。

あなたもプログラミングを学習する前のことを思い出してみてください。

日本語が何も書いていないプログラムを読んでも、何をしているか全く分かりませんでしたよね？

じゃあ今はどうですか？

100行のコメントが付いていないプログラムを読んで、すぐに内容を理解することができますか？

できませんよね？

そうなんです、いくらプログラミングを勉強したとしても、やっぱり僕達が一番素早く理解できるのは日本語なんです。

だからプログラムに説明を書くことがすごく大事なんです！

プログラムにコメントで説明を付けることで、プログラムの概要を瞬時に掴むことができ、作業効率に雲泥の差が出てきます。

他人に見せるプログラムで理解してもらいやすくなるのも1つのメリットですが、後から自分でプログラムを見直した時に「これ、何の処理だったっけ？」となることを防ぐのにも絶大な効果を発揮します。

「自分はちゃんと覚えているから大丈夫！」と思ってても、いざ読み返すと「あれ・・・？」ってなりますからね！マジで。

コメントでプログラムの説明を書く方法はしっかり身に付けておきましょう。

いざプログラムの説明を書くといっても、どう書けばいいか分からないと思います。

なので、プログラマーの観点からコメントで説明を書くポイントを3つ選び抜きました。

次の3つポイントを意識して説明を書いていくようにしましょう。

ポイント1：ファイルの先頭に全体の概要を書く

まず、プログラムを記述しているファイルの一番上に、このファイル全体でどんな処理をしているかを書きます。

これをすることで、ファイルを開いて一目で「このファイルはこんな処理をしているんだな」と読み取ることができるんですね。

複数のプログラムファイルがある場合は、この全体の概要部分を読んで、目的のプログラムがあるかどうか判断しています。

また、複数人で同じプログラムファイルを編集する場合は、いつ、誰が変更を行なったかを明確にする為に変更履歴を残すことがよくあります。

チームで1つのプログラムを扱う場合は、変更履歴も入れておくようにしましょう。

ポイント2：関数のすぐ上に概要、引数、戻り値を書く

次のポイントは、関数全体の説明コメントです。

関数の分け方って、基本的に区切りの良い塊で処理がまとめられています。

なので、コメントで処理内容を書くのにももってこいなんですね。

関数の場合は、ファイルの先頭に書く場合と違って、関数名と引数、戻り値を書くのが一般的です。

関数毎に変更履歴を書く場合もありますが・・・個人的には特にいらないかなと思います。

この関数のコメントで大まかな関数の処理を一発で理解できるようにするってことですよ！

ポイント3：分かりにくい部分の補足を書く

3つ目のポイントは、プログラム中で読んでも分かりにくい箇所を補足する、という点です。

プログラミングをしていると、

「あ～、このif文とfor文の組合せは読んでて分かりにくいなぁ～」

と感じてしまう部分っていうのは出てきちゃいます。

そんな時にコメントで大まかな説明があると、プログラムを解読する時の助けにもなって分かりやすいんですよね。

後は、使っている数字が何を表しているか分かりにくいものの補足ですかね。

ちょうどいい例が、Processingで使う色の指定です。

↓こんなの
background(209.209,209);

これって、RGBでそれぞれの値を指定しているから、結局何色を指定しているか分からないじゃないですか？

だからここに

background(209.209,209); // 背景を灰色に指定

と書いておけば、後で見直した時でもすぐに何色を指定していたかわかるようになります。

それじゃあここまでの3つのポイントを使って、実際にコメントを追記したプログラムを見てみましょう。

//------------------------------------------------
// ファイル名     ：sample.pde
// 概要         ：左上から右下に動く四角形を表示
// 変更履歴     ：2017/10/21　　新規作成
//------------------------------------------------

//------------------------------------------------
// グローバル変数
//------------------------------------------------
// 四角形の描画開始位置
int iRectStartPosX = 20;
int iRectStartPosY = 20;

//------------------------------------------------
// 関数名    ：setup
// 概要      ：プログラムの一番最初に実行する
// 引数      ：無し
// 戻り値     ：無し
//------------------------------------------------
void setup(){
  size(600,400);
}

//------------------------------------------------
// 関数名    ：draw
// 概要      ：定期描画処理（setup終了後から実行）
// 引数      ：無し
// 戻り値     ：無し
//------------------------------------------------
void draw(){
  background(209.209,209);    // 背景を灰色に指定
  
  draw_spiral_rect(iRectStartPosX, iRectStartPosY);
  iRectStartPosX++;
  iRectStartPosY++;
}

//------------------------------------------------
// 関数名    ：draw_spiral_rect
// 概要      ：渦巻き状の四角形を描画する
// 引数      ：int iStartPosX
//              int iStartPosY
// 戻り値     ：無し
//------------------------------------------------
void draw_spiral_rect(int iStartPosX,int iStartPosY){
  int iRectSize = 50;
  int iRectPosX = iStartPosX;
  int iRectPosY = iStartPosY;
  final int RECT_NUM = 5;
  final int RECT_INTERVAL = 5;

  // 段々小さくなる四角形を描画することで渦巻きの四角形を描画する
  for(int i = 1; i <= RECT_NUM; i++){
     rect(iRectPosX,iRectPosY,iRectSize,iRectSize);
    
    iRectPosX = iRectPosX + RECT_INTERVAL;
    iRectPosY = iRectPosY + RECT_INTERVAL;
    
    iRectSize = iRectSize - (2 * RECT_INTERVAL);
  }
 
  return;
}

どうですか？

コメントでプログラムの説明が書かれていない時に比べて、俄然分かりやすくなっていませんか？

これこそがコメントの力なんです！

僕が心からお願いしたいこと

ここまでの内容でコメントの大事さというものが分かってもらえたと思います。

そこで僕からあなたにお願いがあります。

実は今回説明したような、プログラムに付ける説明コメントが、仕事の現場ではめんどくさがられて何も書かれないことが多々あります。

そんなコメントの付いていないプログラムを読み解いて仕事をしていくことって本当にしんどいです。

だから今プログラミングを学んでいて、これからそのスキルを活用していこうとしているあなたには、作成したプログラムにはしっかりコメントで説明を残しておいてほしいんです。

今のうちからコメントを残す癖を付けておかないと、後からすぐに忘れてしまいます。そんなプログラマーを今まで沢山見てきました。

確かに面倒に感じるかもしれませんが、その分の見返りはあなたにやってきます（残業時間が減らせる、会社で良い評価を貰える等…）

最初は上手く内容をまとめられなかったりするかもしれません、それでもいいんです、取り組もうとしていくことが大事ですから。

少しずつ取り組んでいきましょう。

さて、今回はここまでになります！

今回も結構長くなっちゃいましたｗ

搾りカス出ないぐらいまで書くと長くなっちゃうんですよね～。

まだ次回ありますよ！

次回はもう少し短くなるかな？

次はプログラムのデバッグ方法について学習していきます。

この内容もプログラミングスクールではあまり触れられない部分なので、是非読んでくださいね。

それではまた次回お会いしましょう！

　⇒第9回：未だに感激が忘れられない最ッ高のデバッグ方法

　⇒講座一覧へ戻る