Visual Studioでドキュメントコメントを使ってみよう
C#のコードには、説明を書くための「コメント」があります。
たとえば、よく使うのが次のようなコメントです。
// 2つの数を足す
int result = a + b;これは、人がソースコードを読むための普通のコメントです。
C#には、これとは別に
///から始まるドキュメントコメントがあります。
ドキュメントコメントを使うと、Visual StudioのIntelliSenseに説明を表示できます。
今回は、実際にメソッドを作りながら使ってみましょう。
この記事で分かること
//コメントと///ドキュメントコメントの違いsummary・param・returnsの書き方- 書いた説明がIntelliSenseに表示されるまでの確認方法
1. まず普通のメソッドを作る
次のコードを書いてください。
class Calculator
{
public int Add(int x, int y)
{
return x + y;
}
}Add メソッドは、2つの整数を受け取って足し算するだけのメソッドです。
この状態でもプログラムは問題なく動きます。
しかし、別の人が
calculator.Add(10, 20);というコードを見たとき、
xは何を表しているのかyは何を表しているのか- 何が返ってくるのか
といった情報は、メソッド名やコードを読んで判断するしかありません。
そこでドキュメントコメントを付けてみます。
2. メソッドの上で /// と入力する
Visual Studioで、Add メソッドの直前にカーソルを置きます。
そして
///と入力してみてください。
Visual Studioでは通常、自動的に次のような形が作られます。
/// <summary>
///
/// </summary>
/// <param name="x"></param>
/// <param name="y"></param>
/// <returns></returns>
public int Add(int x, int y)
{
return x + y;
}Visual Studioには、C#で /// を入力するとXMLドキュメントコメントのひな形を挿入する機能があります。
少し見慣れない形ですが、最初は3種類だけ覚えれば十分です。
summary
param
returnsです。
3. summary ― メソッド全体の説明
まず、
<summary>
</summary>の中に、メソッドが何をするのかを書きます。
/// <summary>
/// 2つの整数を加算します。
/// </summary>
public int Add(int x, int y)
{
return x + y;
}summary は、
このメソッドは何をするものなのか
を書く場所です。
名前のとおり、「概要」を書きます。
4. param ― 引数の説明
今回の Add メソッドには、
int x
int yという2つの引数があります。
そこで、それぞれを説明します。
/// <summary>
/// 2つの整数を加算します。
/// </summary>
/// <param name="x">1つ目の整数</param>
/// <param name="y">2つ目の整数</param>
public int Add(int x, int y)
{
return x + y;
}param はparameter、つまり引数の説明です。
<param name="x">という部分の x は、
public int Add(int x, int y)の x と対応しています。
5. returns ― 戻り値の説明
Add メソッドには、
return x + y;があります。
つまり、このメソッドには戻り値があります。
戻り値については returns を使います。
/// <summary>
/// 2つの整数を加算します。
/// </summary>
/// <param name="x">1つ目の整数</param>
/// <param name="y">2つ目の整数</param>
/// <returns>xとyを加算した結果</returns>
public int Add(int x, int y)
{
return x + y;
}これで、メソッドの説明が一通り完成しました。
6. IntelliSenseで確認してみよう
次のように Calculator を使ってみます。
Calculator calculator = new Calculator();
int answer = calculator.Add(10, 20);Visual Studio上で
calculator.Addの Add にマウスポインターを合わせてみてください。
すると、メソッドの情報と一緒に、
2つの整数を加算します。という説明が表示されます。
さらに、
calculator.Add(と入力すると、引数の情報も表示されます。
Visual Studioでは、XMLドキュメントコメントの内容がQuick Infoやパラメーター情報に利用されます。
ここが普通の // コメントとの大きな違いです。
7. 普通のコメントとの違い
たとえば、
// 2つの整数を足す
public int Add(int x, int y)
{
return x + y;
}と書いても、そのコメントは基本的にソースコードを読んでいる人にしか見えません。
一方、
/// <summary>
/// 2つの整数を加算します。
/// </summary>のようなドキュメントコメントは、Visual Studioが内容を理解できます。
つまり、
// → ソースコードを読む人向け
/// → メソッドやクラスを使う人向けと考えると分かりやすいでしょう。
8. クラスにも書ける
ドキュメントコメントは、メソッドだけではありません。
クラスにも付けられます。
/// <summary>
/// 計算処理を行うクラスです。
/// </summary>
class Calculator
{
/// <summary>
/// 2つの整数を加算します。
/// </summary>
/// <param name="x">1つ目の整数</param>
/// <param name="y">2つ目の整数</param>
/// <returns>xとyを加算した結果</returns>
public int Add(int x, int y)
{
return x + y;
}
}プロパティなどにも付けることができます。
/// <summary>
/// 生徒の名前を取得または設定します。
/// </summary>
public string Name { get; set; }C#のドキュメントコメントは、クラス、メソッド、プロパティ、フィールドなどの型やメンバーに付けられます。
9. void のメソッドには returns は必要ない
たとえば、
public void ShowMessage(string message)
{
Console.WriteLine(message);
}の場合、戻り値はありません。
そのため、
/// <summary>
/// メッセージを画面に表示します。
/// </summary>
/// <param name="message">表示する文字列</param>
public void ShowMessage(string message)
{
Console.WriteLine(message);
}で十分です。
returns を無理に書く必要はありません。
実際、void のメソッドの上で /// と入力すると、Visual Studioは returns の行を作りません。
10. まずは3つだけ覚えよう
ドキュメントコメントには、ほかにもたくさんのタグがあります。
たとえば、
remarks
example
exception
seealso
inheritdocなどがあります。MicrosoftのC#ドキュメントでも、これらは標準的なドキュメント用タグとして紹介されています。
しかし、最初から全部覚える必要はありません。
まずは、
| タグ | 役割 |
|---|---|
<summary> | クラスやメソッドの説明 |
<param> | 引数の説明 |
<returns> | 戻り値の説明 |
この3つで十分です。
11. 練習してみよう
次のメソッドに、自分でドキュメントコメントを書いてみてください。
public double GetAverage(int score1, int score2)
{
return (score1 + score2) / 2.0;
}たとえば次のようになります。
/// <summary>
/// 2つの点数の平均値を求めます。
/// </summary>
/// <param name="score1">1つ目の点数</param>
/// <param name="score2">2つ目の点数</param>
/// <returns>2つの点数の平均値</returns>
public double GetAverage(int score1, int score2)
{
return (score1 + score2) / 2.0;
}書いたら、別の場所から GetAverage を呼び出して、IntelliSenseに説明が表示されるか確認してください。
12. なぜドキュメントコメントを書くのか
プログラムは、書いて終わりではありません。
あとから、
- 自分で読み直す
- 他の人が使う
- チームで共同開発する
- クラスを別のプロジェクトから利用する
ことがあります。
そんなとき、
public int Calculate(int x, int y)だけを見るよりも、
商品の税込価格を計算します。
x : 税抜価格
y : 税率
戻り値 : 税込価格と説明が表示されたほうが、使い方が分かりやすくなります。
ドキュメントコメントは、
「コードの中に、使い方の説明書を書く仕組み」
と考えるとよいでしょう。
まとめ
C#では、
///から始まるコメントをドキュメントコメントと呼びます。
まずは次の3つを覚えましょう。
<summary>メソッドやクラス全体の説明。
<param>引数の説明。
<returns>戻り値の説明。
普通のコメントはコードを読む人のためのものですが、ドキュメントコメントはそのクラスやメソッドを使う人のための説明にもなります。
Visual StudioのIntelliSenseに自分が書いた説明が表示されるところまで、ぜひ実際に試してみてください。