これだけは書いておきたい！C#のドキュメントコメント

はじめに

プログラマーとして開発する場合、特に仕事ではたいてい複数人の開発になります。
そうした時に重要となるのはコードの読みやすさ、追いやすさですね。
この記事ではその中でも最低限書いておきたいC#のドキュメントコメントについて取り上げようと思います。
※内容は個人の感想に理由付けされている程度です！実際にはチームの方針に従って開発してください。

最初に結論

先に結論ですが

• publicなメンバには必ずドキュメントコメントを書く
• 書いておきたいタグ
  • メソッド
    • summary
    • param
    • returns
  • その他
    • summary

だけは書いておきたいです！
こうすることでコードを辿ることなくエディタ上でクラスやメソッドが何者かわかります。

なぜこれだけは書いておきたいのか

summary

最重要タグです。クラスにメソッド、プロパティなどpublicであればどれにでも付けたいです。
多くの書籍では名前をわかりやすくすることでコードの読みやすさを高めることを推奨していますし、それに越したことはないですが、僕の経験上名前だけで解決できないことはちょくちょく遭遇します。あと名付け戦争が起きることも
summaryを書くことによってエディタに何をするものなのか表示されるので必要以上に名前で悩む必要がなくなります。それと同時に注意点等も入れておけるので間違った利用を防げます。

param

型と名前で推測できることは多いです。
ただ、引数はメソッドやプロパティと違って長くなるとメソッド定義自体が長く読みにくいものになります。
それであれば、名前は簡潔にしておいてparamタグによる説明で補足する方が全体として読みやすくなります。

returns

メソッドの出力を表すので非常に重要です。
例えば入力からどう作られたものなのかや処理に失敗した場合は何が返るのかという点を記載しておくことで、読み手にメソッド内部の処理をある程度理解してもらえます。
特に後者は明確に書いてあることにより呼び出し元で成否判定する際、迷わずに済みます。

実例

ドキュメントコメントが真価を発揮するのはエディタ上なのですが実例で比較してみます。
例ではどこかの商店の取り扱い商品のリストを表すクラスと、商品名から商品の値段を取得するメソッドを書いています。

// ドキュメントなし
public class ProductList
{
    public int GetPrice(string targetProductName)
    {
       int price = -1;
       // 商品名から探してpriceを取得する処理
       return price;
    }
}

// ドキュメントあり
/// <summary>取り扱い商品のリスト</summary>
public class ProductList
{
    /// <summary>商品名から値段を取得する</summary>
    /// <param name="name">値段を取得したい商品名</param>
    /// <returns>商品が見つかればその値段、見つからなければ負数</returns>
    public int GetPrice(string name)
    {
       int price = -1;
       // 商品名から探してpriceを取得する処理
       return price;
    }
}

どうでしょうか？
ドキュメントコメントがあるだけで内部実装まで追わなくてもGetPriceメソッドを安心して使えるのではないでしょうか。

まとめ

publicな要素にはsummaryを、メソッドであればparamやreturnsも書いておきたいですね！

参考資料