【C#】ソースコードにXMLコメントを書く方法

C#でソースコードにコメントを付けるには「//」か「/* */」で行うのが一般的ですが、それはあくまでもインラインコメントであり、ソースコードに対してコメントを残す方法です。それに対して「XMLコメント」というものがあります。

XMLコメントはソースコード内に記述するようなコメントではなく、クラスやコンストラクタ、メソッドやプロパティに対して付けるコメントです。このコメントも重要視されているので、しっかりと覚えておく必要があります。

XMLコメントとは

まずはxmlについて基礎知識を紹介します。XMLとは「Extensible Markup Language」の略称であり、「拡張可能なマークアップ言語」と日本語で訳されることが多いです。呼び方は「エックスエムエル」で大丈夫です。ウィキペディアでは以下のように解説されています。

Extensible Markup Language（エクステンシブルマークアップランゲージ）は、基本的な構文規則を共通とすることで、任意の用途向けの言語に拡張することを容易としたことが特徴のマークアップ言語の総称である。一般的にXML（エックスエムエル）と略称で呼ばれる。JISによる訳語は「拡張可能なマーク付け言語」と定義している。

– Extensible Markup Language | Wikipedia

データのやりとりや管理を簡単にする目的で使われ、記述形式がわかりやすいという特徴があります。形式的にはウェブサイトを作成するときに使用する「HTML」のような感じだと思ってもらえればよいと思います。

XMLコメントは「xml形式でC#のソースコードにコメントを記載する」ことだと思ってもらえれば十分です。XMLのことを詳しく知る必要はなく、当記事で紹介するものだけ覚えておけば十分です。それ以外には、ほとんど使用しないといっても過言ではありません。

xmlコメントを付ける方法

C#のソースコードでXMLコメントを付けるには、「/（スラッシュ）」を3回押下することで自動的に挿入されます。XMLコメントは以下のような形式でC#のソースコードに表現されます。

/// <summary>
/// 
/// </summary>
class Car
{
}

「summary」と書かれたタグの中にコメントを書くのが良いとされます。上記のような感じでコメントを書くとよいでしょう。

/// <summary>
/// 車クラス
/// </summary>
class Car
{
}

引数がない場合は上記のように「summary」タグだけが表示されます。ほかにもプロパティやコンストラクタ、メソッドなどにも使うことができます。また、引数があるメソッドは以下のように表示されます。

/// <summary>
/// 
/// </summary>
/// <param name="speed"></param>
public void Drive(int speed)
{
    Console.WriteLine(speed.ToString() + "キロで走行中。");
}

引数がある場合は「param name=”〇〇”」と書かれたタグが表示されます。ですので、こういう場合には以下のようにコメントを付けるとよいかと思います。

/// <summary>
/// 車を走らせる処理を行います。
/// </summary>
/// <param name="speed">速度</param>
public void Drive(int speed)
{
    Console.WriteLine(speed.ToString() + "キロで走行中。");
}

summaryタグ内にはコメントを付けるのがあたり前ですが、パラメータタグに対してコメントを付けるかどうかは人や案件によりけりです。付けられる余力があったり、複雑な引数である場合にはコメントを書いたほうが他の人が読みやすいです。