c# - .Net コードを文書化する最良の方法は何ですか?

Question

あなたも私も、コード用のドキュメントを作成するのは本当に退屈であることを知っています。コード用のドキュメントを作成する経験を共有するためのディスカッションとしてこれを開きました。

プロジェクトドキュメントは、UML を使用してプロジェクト全体、アルゴリズム、設計、アーキテクチャを記述することができるプロジェクトドキュメントのコードドキュメントとは異なると思います。他の開発者が使用するコード。ディスカッションのテーマは次のとおりだと思います:

1.ドキュメントの生成に役立つとわかっているツール

score 1 · Accepted Answer

これは、コミュニティが一般的に反対する傾向があるものの1つです。一般的ではありません...コードドキュメントはAGoodThing™であることは誰もが認めていると思いますが、それをどのように行うかは個人的な問題です。

これが私の見解です：

苦痛だとは思いますが、インラインドキュメントは、集中力を維持するのに役立つだけでなく、コードを振り返るときに参照できる情報を提供します。

1）Sandcastleを使用して、ライブラリからヘルプファイルを生成します。これは、XMLドキュメントコメントでドキュメント化します。

2a）パブリックフィールド、プロパティ、およびメソッドについては、常に妥当なXMLドキュメントを提供してください。ただ置くのではなく/// <summary>FieldName</summary>、フィールドの目的を説明してください。

2b）インラインコメントは慎重に使用してください。すべての行にコメントを付けるのではなく、何か面白いことや面白い方法でコードのブロックにコメントを付けてください。そうすれば、次にコードを読んだときに、あなた（または他の誰か）がそれを明確に理解できます。

3）絶対にびっくりする-絶対に。私自身のコードを読むことは通常非常に簡単ですが、すべての開発者は異なった働きをします。他の誰かが書いたコードがある場合、コメントは理解と理解の違いを生む可能性があります。