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

xmlコメントを付けよう

以上、簡単ですがXMLコメントを付ける方法を解説しました。XMLコメントは「題名」や「見出し」のようなイメージでコメントを付けるとよいですね。一般的なコメントは、本当に「単なるコメント」として使用しますが、こちらは大きな単位で使用することが多いです。

コメントは他の人がソースコードを読む時などで重要な役割を果たし、ソースコードの可読性において大切ですので、できる限り記述するようにしたほうが良いかもしれません。