1

C# コードの XML ドキュメント コメントに関しては、次の 2 つの考え方があります。

  1. Robert C. Martin のクリーン コード アプローチ: 「
    クラス、メソッド、変数に慎重に名前を付けて作業の意図を表現する場合、
    コメントは必要ありません。」
  2. すべてのパブリック クラス、インターフェイス、メソッド、およびプロパティにコメントする必要があります

プログラマーは怠け者なので、GhostDoc や Resharper などのツールを使用して、XML ドキュメント コメントを自動的に生成します。これらのツールの目的は、プログラマが簡単に拡張できる基本的なコメントを提供することでした。しかし、現実には、生成されたコメントの多くは変更されないままです。したがって、明快さや保守性の点で、コードに価値はありません。変更されずに生成された XML ドキュメント コメントは単なるノイズです。ある意味で、それらは DRY 原則違反の一種です。

私のチームでは、これらの「ノイズコメント」の無用さを認識しています。ただし、「コメントをまったくしない」という方法もすべて行いたくありません。思いついたアイデアは、すべてのパブリック メンバーに対して次のようなスタブを生成することでした。

/// <summary>
/// TODO
/// </summary>

誰かが TODO コメントをそのままにしてコードをチェックインすると、ビルド (TFS2013 を使用) が壊れるはずです。

私の質問は次のとおりです。

  • 誰かがこのようなことをしましたか？どのように？
  • XML ドキュメントのジレンマを解決する他の方法はありますか?
  • 私の懸念は、文書化されていない既存のコードに取り組む必要があるチーム メンバーの作業が遅くなることです。チーム メンバーは、小さな変更でもチェックインできるようにするためにコード考古学を行う必要があります。それを防ぐための考えはありますか？
4

1 に答える 1

1

理想的ではありませんが、すでに組み込みのプロビジョニングがあります。

  • コメントジェネレーターを使用しないでください
  • 提案されたスタブを使用しないでください
  • Warning-Level = 4 でコンパイルする
  • [x] XML ドキュメント ファイルを確認してください
  • [x] 警告をエラーとして扱うにチェックを入れます
于 2015-10-18T10:39:11.033 に答える