C#でソースコードにコメントを付けるには「//」か「/* */」で行うのが一般的ですが、それはあくまでもインラインコメントであり、ソースコードに対してコメントを残す方法です。それに対して「XMLコメント」というものがありますXMLコメントはソースコード内に記述するようなコメントではなく、クラスやコンストラクタ、メソッドやプロパティに対して付けるコメントです。このコメントも重要視されているので、しっかりと覚えておく必要があります。
XMLコメントとは
まずはxmlについて基礎知識を紹介します。XMLとは「Extensible Markup Language」の略称であり、「拡張可能なマークアップ言語」と日本語で訳されることが多いです。呼び方は「エックスエムエル」で大丈夫です。ウィキペディアでは以下のように解説されています。
Extensible Markup Language(エクステンシブル マークアップ ランゲージ)は、基本的な構文規則を共通とすることで、任意の用途向けの言語に拡張することを容易としたことが特徴のマークアップ言語の総称である。一般的にXML(エックスエムエル)と略称で呼ばれる。JISによる訳語は「拡張可能なマーク付け言語」と定義している。
データのやりとりや管理を簡単にする目的で使われ、記述形式がわかりやすいという特徴があります。形式的にはウェブサイトを作成するときに使用する「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コメントは「題名」や「見出し」のようなイメージで付けるとよいです。一般的なコメントは「単なるコメント」として使用しますが、こちらは大きな単位で使用しましょう。
コメントは他の人がソースコードを読む時などで重要な役割を果たし、ソースコードの可読性において大切なので、できる限り記述するようにするのがベストです。改めてコードを読むときにとても役に立ちます。