C#にドキュメントコメントを入れよう

コメントを入れよう

プログラムの中のコメントは、やはり必要です。
コードの可読性を向上させ、チーム開発を円滑に進め、長期的にはコードの保守性を高めます。

すでにご存知のことと思いますが、C#はXMLドキュメントコメントを設定することができます。関数やクラスのコメントを所定のルールで作成すると、IDEのサポートを受けることができます。
具体的には、Visual StudioやRiderなどのIDEで, コード補完時にツールチップとしてコメント内容が表示されます。関数の定義元に戻り、コードを読み返す必要がなくなります。

知らなかった方は、これを機会に利用を検討されてください。

C#の場合

サンプルのクラスを例に、動作を確認してみましょう。

以下は、本のタイトルと著者名をプロパティに持つBookクラスです。
summaryやreturnsのタグで囲まれている箇所が、コメントです。

Program.cs

/// <summary>
/// 本の情報を管理するクラスです。
/// </summary>
public class Book
{
    /// <summary>
    /// 本のタイトルを取得または設定します。
    /// </summary>
    public string Title { get; set; }

    /// <summary>
    /// 本の著者を取得または設定します。
    /// </summary>
    public string Author { get; set; }

    /// <summary>
    /// 本の情報を文字列形式で取得します。
    /// </summary>
    /// <returns>
    /// タイトルと著者を含む文字列。
    /// </returns>
    public string GetBookInfo()
    {
        return $"タイトル: {Title}, 著者: {Author}";
    }
};

このクラスのインスタンスを、コンソールに出力するのが以下のコードです。
GetBookInfoで文字列として値が返ってきます。

Class.cs

var book = new Book
{
    Title = "吾輩は猫である",
    Author = "夏目漱石"
};

Console.WriteLine(book.GetBookInfo());

GetBookInfo()にマウスカーソルをかざすと, 直前に作成したコメントの内容がホバー表示されます。現在のカーソルの位置で、関数の仕様を把握することができます。

まとめ

C#のドキュメントコメントのルールに従うことで、IDEのサポートを最大限受けることができます。過去のコードを振り返るのではなく、コードを書くという建設的な作業に集中できるというわけです。

XMLのタグは他にもあるため、調べてみてください。

参考にした情報