Visual Studio 2019 v16.4以降でC#を使う場合にはinheritdocを使った方がいいという話

はじめに

筆者がVisual Studio 2019 v16.4以降でC#で開発をしていた際にinheritdocを使えることを知って、便利だなと思ったので、inheritdocの使い方について本記事ではまとめます。

そもそもinheritdocとは

基底クラス、インターフェースのメソッドからXMLコメントを継承するためのXMLタグです。
詳細はこちらのMS公式の説明を参照ください。
Visual Studio v16.4でinferitdocに対応するようになりました。

inheritdocを知らなかったときの開発上での問題点

例えば、以下のような計算機インターフェースがあるとします。

interface ICalculator
{
    /// <summary>
    /// 足し算する
    /// </summary>
    /// <param name="term1">項1</param>
    /// <param name="term2">項2</param>
    /// <returns>計算結果</returns>
    double Add(double term1, double term2);

    /// <summary>
    /// 引き算する
    /// </summary>
    /// <param name="term1">項1</param>
    /// <param name="term2">項2</param>
    /// <returns>計算結果</returns>
    double Subtract(double term1, double term2);
}

計算機インターフェースを実装する計算機クラスでは、AddメソッドとSubtractメソッドのコメントがインターフェースと同じなので、コピペして作成することにしたとします。
以下のような感じです。

class Calculator : ICalculator
{
    /// <summary>
    /// 足し算する
    /// </summary>
    /// <param name="term1">項1</param>
    /// <param name="term2">項2</param>
    /// <returns>計算結果</returns>
    double Add(double term1, double term2){...}

    /// <summary>
    /// 引き算する
    /// </summary>
    /// <param name="term1">項1</param>
    /// <param name="term2">項2</param>
    /// <returns>計算結果</returns>
    double Subtract(double term1, double term2){...}
}

このようにインターフェースと実装クラスでメンバのコメントが同じである場合、インターフェースのメンバが多いほどクラス側にコメントをコピペするといったことが多くなり、コメントを付ける手間が大きくなります。また、インターフェースのコメントと実装クラスのコメントを追従させるのが大変になるという問題も起きます。

inheritdocを使うとどうなるか

inheritdocを使うと計算機クラスから計算機インターフェースでメンバのコメントの同期ができます。
以下のように書くことで、計算機クラスのAdd,Subtractメソッドのコメントは、計算機インターフェースのAdd,Subtranctメソッドのコメントと同期されます。さらにinheritdocではインターフェースと実装クラスで常にメンバのコメントが同期するので、計算機インターフェースのメンバのコメントを変更した際に計算機クラスのメンバのコメントを修正する必要がありません。

class Calculator : ICalculator
{
    /// <inheritdoc/>
    double Add(double term1, double term2){...}

    /// <inheritdoc/>
    double Subtract(double term1, double term2){...}
}

まとめ

Visual Studio 2019 v16.4以降でC#開発時に使った方が良いinheritdocタグについてメリットを中心にまとめました。
インターフェースと実装クラス間でのメンバコメントのコピペや追従をする必要がなくなるので、積極的に使っていきたいですね。