大事なことは書きましょう

みなさんお疲れ様です。
連載担当の後藤です。
今日は、コメントの書き方を勉強していきましょう。

1. コメントって何だろう？
2. 何をコメントするか
3. なにをコメントすべきでないか
4. コメントの書き方
5. コメントをつけてみよう
6. まとめ

コメントって何だろう？

コメントは、今あるメジャーなプログラミング言語のほとんどにある仕組みです。
ソースコードの中に、ソースコードだけではあらわせないことを、メモ書きするためのものです。
ソースコードの一部ではないので、実行時にコンピューターは、コメントを無視します。
人間だけが、中身を読むことができるのです。

何をコメントするか

コメントすべきことは、大きく分けて3つです。

1. 何が行われているか
2. なぜそのソースコードを書いたか
3. 欠陥のあるコードの改善策

コメント対象1. 何が行われているか

第1回でも触れたように、
なるべく自然な英語に近い形で
読み書きできるように、
今のメジャーなプログラミング言語は設計されています。

C#も、ソースコードを読んだだけで、
何が行われているのかがわかることを目指して作られています。

なので、理想どおりにいけば、何が行われているかはソースコードだけでわかる。
コメントはいらない、となるはずですが・・・

実際には、そのソースコードで何が行われているかを、
コメントとして書かなければいけないことがあります。
以下の二つのケースが想定されます。

ケース1. 書き手と読み手のどちらか（あるいは両方）がプログラミングが苦手
ケース2. 書き手と読み手のどちらか（あるいは両方）が英語が苦手

ケース1. 書き手と読み手のどちらか（あるいは両方）がプログラミングが苦手

プログラミング初心者に解説、説明するためのソースコードには、
ソースコードの意味を人間の言語で翻訳、解説する必要があります。

たとえば、C#初心者が、
『Console.WriteLine(”Hello World!”);』といわれても、
『？？？？？？？？？』ですよね。
だから、以下のように、人間の言語（ここでは日本語）で翻訳、解説します。

// 『Console』はコマンドラインの画面
// 『Console』の後ろの『.』は、ここでは日本語の『が』と同じ
// 『WriteLine()』は画面に表示すること
// 『()』の中身の”Hello World!"が表示されるもの
// 『;』が、日本語の『。』と同じ文末のマーク。
// 全体で、『コマンドラインの画面が"Hello World!"を表示する。』という意味。
Console.WriteLine("Hello World!);

プログラミング開発をする際に、チームメンバーにプログラミングが苦手な方がいる場合、
やはりコメントをつかって、何が行われているかを解説する必要があります。

ケース2. 書き手と読み手のどちらか（あるいは両方）が英語が苦手

日本は非英語圏なので、この理由は大きいです。
C#が人間の英語に近く作られているといっても、
英語が不得意な人間にはそもそもちんぷんかんぷんな宇宙語です。
プログラミングを学ぶ過程で学んでいけるとしても、
やはり日本語での解説を、コメントとしてつけたほうが親切な場合があります。

コメント対象2. なぜそのソースコードを書いたか

書き手と読み手が両方とも、プログラミングも英語も十分熟練していたとしましょう。
理論上は、この場合『何をやっているか』を説明するコメントは不要です。

そうだとしても、別の種類のコメントは書かないといけません。
それが、『なぜそのソースコードを書いたか？』を記録するときです。
より正確に言うと、『なぜ同じ意味を表せる複数の表現のうち、その1つの表現を選んでソースコードに書いたか？』を、
説明しなければいけません。
これを書くことで、ソースコードを読んだチームメンバーが、
『この人がこの表現を選んだ理由がわかった。私は賛成/反対だ。理由は・・・』と
議論のたたき台に使うことが出来ます。

たとえば、以下の場合です。

// お勧めしない: !(4 == 4);
// 読んでる皆さんも、もう否定等号演算子を理解しているはず。
// 否定等号演算子を使って、短く書くべき。
4 != 4;

コメント対象3. 欠陥のあるコードの改善策

人間の言語では、文章を書くときに、何回も見直しが必要です。
『ここは変えたほうがいいかな？』という部分は、マークして
後で見直します。

C#のソースコードを書くときも、もちろん見直しは必須です。
そのとき、『これ直したほうがいいかな？』という部分は、
コメントでマークします。
自分が後で見直しするヒントになりますし、
チームメンバーが見た場合も、改善策を考えるたたき台になります。

実例を下に挙げます。

// 修正したほうがいい: 『+』記号は要らない。なくても読みやすさは落ちない。
Console.WriteLine("これは” + ”欠陥");

なにをコメントすべきでないか

何をコメントすべきかは述べました。
では、何をコメントすべきでないかをご説明します。

1. すでに使わなくなったソースコード
2. たまっているストレス

コメントするな1. すでに使わなくなったソースコード

すでに使わなくなったソースコードは消してください。
バージョン管理システムを使えば、前のバージョンのソースコードを見ることが出来ます。
コメントにしてはいけません。

実例を挙げます。
繰り返しますが、これは真似してはいけない例です。

// 2017_05_08に変更
// !(4 == 3);
4 != 3;

コメントするな2. たまっているストレス

残念なことに、仕事でコードを書いていくと、
時にはストレスをためてしまうことがあります。
カウンセラーさんに話しましょう。
コメントに書きたくなりますが、
お控えください。

コメントの書き方

いよいよ具体的なコメントの書き方を練習しましょう。
コメントには1行コメントと複数行コメントがあります。
以降、順番に見ていきましょう。

一行コメント

1行だけコメントを書くときの仕組みです。
2行以上書くときは、毎行1行コメントを繰り返すことになります。
使う記号は『//』です。

実例を見ていただきましょう。

// ここはコンピューターさんには読めません
// 人間だけに必要な情報を書きましょう。
Console.WriteLine("Hello World!”);

複数行コメント

2行以上にわたってコメントを書くときに適した仕組みです。
コメントの部分を、『/』と『/』でサンドイッチしてあげます。

実例はこちらになります。

/*
  ここはコンピューターさんには読めません。
　人間だけに必要な情報を書きましょう。
*/
Console.WriteLine("Hello World!");

複数行コメントの入れ子構造は出来ません。
ご注意ください。

/*
　　この中は正常なコメントです。
 /*
　　この中も正常なコメントです。
 */　// 左側のコメント終了記号でコメントは終了です。

*/ // 左側の終了記号はエラーです。すでにコメント部分は終了しているからです。

コメントをつけてみよう

おつかれさまです。
最後に、これまで学んできたことを使って、
実際にコメントをつけていただきます。

問題1. 以下のコードが何をやっているかを、C#初心者にわかるよう日本語でコメントしてください。

課題コード

Console.ReadLine();

問題2. 4は3以上であることを表すため、AでなくBのコードを選んだ理由を日本語でコメントしてください。

A. 選ばなかったコード

 (4 > 3) || (4 == 3);

B. 選んだコード

4 >= 3;

問題3. 以下のコードは欠陥があります。改善策を日本語でコメントしてください。

課題コード

Console.WriteLine("このコードには欠陥があります。");
   Console.WriteLine("どれが欠陥かな。");   
           Console.WriteLine("みつけてみてね");

まとめ

みなさんお疲れ様です。
これで、ソースコードにコメントを着けることができるようになりました。

次回は、データ型について学びましょう。

ゲーム制作関連のオススメ連載リンク

とっても手軽なゲーム制作体験！
Unityゲーム開発基礎

実際のリリースゲームを題材にしたハンズオンゲーム制作連載
実践unityゲーム開発