コード中に度々目にする例のアレの正体
他人が開発したコードを読んでいると、時々メソッド(関数)の前などにコメントとして下のような記述をみたことがありませんか。
C#
/// <summary>
/// (メソッドの説明が書かれている)
/// </summary>
void ShowCommet()
{
Debug.Log("Comment");
}
このメソッド直前にある<summary>
と</summary>
のコメントはdocument comment(ドキュメントコメントと呼ばれています。
ドキュメントコメントとは?
ドキュメントコメントは、その名の通り、ドキュメント生成用のコメントです。プログラムの説明用に残せるコメントでもあり、設定によってはドキュメントコメントをもとにXML形式で出力できます。(この記事ではxml形式で出力する方法は割愛しています)
また、visual studio上で、ドキュメントコメントが併記されているメソッドにマウスカーソルを合わせると、下図のように説明が表示されることも特徴です。
サンプル用メソッド
/// <summary>
/// テスト用メソッド。コンソールに出力します。
/// </summary>
void ShowComment()
{
Debug.Log("hello world!");
}
-
ドキュメントコメントは形式化されているため、例えば上の
<summary>
の直前は///
のようにスラッシュが3本ですが、これが2本のスラッシュ//
だとドキュメントコメントとはならず、メソッドにマウスカーソルを合わせても何も表示されません。
先ほどのコメントで実際に<summary>
の直前を//
で指定したときの表示が下図になります。
- はじめてソースコードを見た人に理解の助けとなるような説明を残せることができますので可読性の向上につながります。
- 他にも、関数の引数や返り値の説明もドキュメントコメントとして残せます。引数として指定したnum1、num2にマウスカーソルを合わせると下図のように表示してくれます。
サンプル用メソッド
/// <summary>
/// テスト用メソッド
/// </summary>
/// <param name="num1">コンソールで1つ目に表示させたい数値が引数num1です。</param>
/// <param name="num2">コンソールで2つ目に表示させたい数値が引数num2です。</param>
/// <returns>引数で受け取った値の合計値を返す</returns>
int ShowComment(int num1, int num2)
{
Debug.Log("num1:"+ num1);
Debug.Log("num2:"+ num2);
return num1 + num2;
}
ドキュメントコメントの種類
ドキュメントコメントは上記で紹介したメソッドの説明用だけじゃなくても他にも様々な形式が存在します。(ちなみに、自分は全く覚えてません。)
参考として公式サイトのリンクを張っておきます
C#版ドキュメントコメントの説明 Microsoft公式サイト
まとめ
- ドキュメントコメントは形式が定められている
- ドキュメントコメントはプログラムの説明用に残せる、ドキュメント生成用のコメント