コメント

概要

プログラムには自然言語で注釈を入れましょう。

ポイント

• コメント： プログラムとは関係ない、自然言語で書かれた注釈。
• /* 複数行にわたるコメント */
• // 行末までのコメント
• 注意： 可能な限りコメントなんて書かなくても分かりやすいきれいなコードを書くのが理想的。

コメント

C# などの、自然言語に近い形で書けるプログラミング言語(このようなものを高級言語と呼ぶ)は、 人間が理解しやすい形でプログラムを記述するために作られたものですが、 やはり、自然言語による説明なしでは、理解のしやすさに限界があります。 プログラムのソースを理解しやすくするためには、人間の言葉で処理の概要や変数の意味などを書いておくのが一番です。

そのため、C# などの高級言語では、プログラムの流れとはまったく関係なく、人間の言葉で注釈を入れておくための仕組みを用意してあります。 このように、プログラム中に自然言葉で注釈を入れることをコメントといいます。

C#では、コメントの書き方には2通りあります。 1つは /* と */ でコメントを囲う 方法で、もう1つは // の後ろにコメントを書く 方法です。 /* と */ で囲われた文字列は、コメントとして扱われ、コンパイラに無視されます。 このコメントは複数行にわたって書くことも可能です。 ただし、/* と */ を2重にして使うことは出来ません。 また、// の後ろに続く文字列もコメントとして扱われます。 行末までがコメントとなります(そのため、複数行にわたるコメントは書けません)。 /* */ と違い、コメントを閉じ忘れるということが無いので便利です。

/*
 この部分はコメントです。
 複数行にわたるコメントを書くことも可能です。
*/

// このようなコメントもかけます。
// 行末までがコメントになります。

/*
 でも、このコメントを
  /* こんな風に */
 2重に使っちゃだめ。
 このコメントはエラーになります。
*/

どんなにプログラミングの得意な人でも、コメントのまったく入っていないソースファイルの内容を理解するのは困難です。 自分で書いたソースですら、数ヶ月も経つとどこに何を書いたのか分からなくなることがしばしばあります。 そういうことにならないためにも、ソースファイル中にはしっかりとコメントを入れるようにしましょう。

以下にコメントを挿入すべきポイントを示す例を挙げます。 プログラム中には現時点ではまだ説明していないことも使っていますので、 プログラムの内容自体は理解できないと思いますが、 ポイントとなる点は背景色を変えて強調してありますので、 とりあえずそこだけ流し読みしてみてください。

サンプル

コメントの付け方の例を示します。 サンプルとはいえ、コメント入れ過ぎかも。

C# みたいな、割と意図どおりにプログラムコードを書ける言語において、 「コメントが付き過ぎ」あるいは「コメント書かなきゃ分からない」ってのは、 コードの出来が悪い可能性が高いです。

using System;

// クラスの前にはそのクラスの説明を書いたほうがいい。

//「///」から始まるコメントはC#では特別な意味を持つ。
// 詳しくは「XML Documentation」で説明する。

/// <summary>
/// コメント付けのサンプルプログラム。
/// ここでは例として配列で与えられたデータ列の平均値と分散を求めて表示する。
/// </summary>
class CommentSample
{
  static void Main()
  {
    // 変数名の後に変数の説明を書いたりすることも。
    // ほんとは、コメントが無くても意味の分かる変数名を付けるべき。

    int[] a = new int[30]{
      455,  58,   8,   7, 987,  56,   2,  64, 698,  79,
       98,  79,  45, 465, 167,  97,  94, 657, 237, 587,
      687, 654, 647,   4, 654, 984,   8, 489,   7,  22}; // データ列
    double mean; // 平均値
    double var;  // 分散

    // 処理の区切りごとに、処理の内容の簡単な説明を書いたり。
    // これも、できれば、コメントなんて書かなくても分かりやすい簡潔な処理を書く方がいい。
    // (「関数の前にだけ説明があれば十分」と言うのが理想。
    //   要するに、処理の区切りごとに関数に分かれてる方がいい。
    // コメントが必要そうな処理の区切りがあったら、そこを関数化する。)

    // データ列 a の平均値と分散を求める
    CalcMean(a, out mean, out var);

    // 結果の表示
    Console.Write("平均 : {0}, 分散 : {1}\n", mean, var);
  }//Main
  // ↑ 関数やループの中身が長くなって 括弧{} の左右の対応が分かりづらくなった場合、
  // } の後ろにコメントを入れておくと括弧の対応が分かってよい。
  // これも、{} の対応が分かりにくくならない程度に処理を分ける方が理想的。

  // 関数の前にはその関数の説明を書く。

  /// <summary>
  /// 配列に入ったデータの平均値と分散を求める
  /// <param name="array">与えられたデータ列</param>
  /// <param name="mean">arrayの平均値(出力)</param>
  /// <param name="var">arrayの分散(出力)</param>
  /// </summary>
  static void CalcMean(int[] array, out double mean, out double var)
  {
    int sum = 0;     // 合計
    int sq_sum = 0;  // 二乗の合計

    // データ列の合計と二乗の合計を求める
    foreach(int n in array)
    {
      sum += n;
      sq_sum += n*n;
    }
    // 平均値と分散を計算
    mean = (double)sum / array.Length;
    var = (double)sq_sum / array.Length - mean*mean;
  }//CalcMean
}

平均 : 303.2, 分散 : 99802.0266666667

ここで、/** もしくは /// で始まるコメントには特殊な意味があります。 これらはドキュメンテーションコメントと呼ばれるもので、 「XML Document」 で説明します。