15

おはよう、午後、夕方、または夜 (タイムゾーンによって異なります)。

これは、C# 内の XML コメントに関する一般的な質問です。私は自分のプログラムにコメントすることにあまり熱心ではありませんでした。私は常に、より詳細な変数/プロパティ/メソッドの命名者であり、コード自体に語らせてきました。かなり紛らわしいものをコーディングしている場合はコメントを書きますが、ほとんどの場合、多くのコメントは書きません。

.NET、Sandcastle、および codeplex のヘルプ ファイル ビルダーの XML コメントについて読んでいたところ、自分のコードを文書化し、自分のコードを掘り下げなければならない人のために素敵で役立つドキュメントを生成したいと思うようになりました。私がもうここにいないときのコード。

私の質問は、標準と慣習についてです。「良い」XML コメントのガイドはありますか? すべての変数とプロパティにコメントする必要がありますか? すべての方法？私は基本的に、サンドキャッスルによって適切なドキュメントにコンパイルされる優れたコメントを書く方法に関するヒントを探しているだけなので、他のプログラマーが私のコードで作業する必要があるときに私の名前を呪うことはありません。

あなたのアドバイスと提案を事前にありがとう、Scott Vercuski

4

6 に答える 6

10

個人的には、すべての public および protected メソッドに XML コメントがあることを確認します。また、エンド ユーザーのヘルプ ドキュメントだけでなく、Intellisense も提供します。過去に、プライベート スコープの宣言にも含めましたが、メソッドが短く適切である限り、100% 必要だとは感じていません。

XML のコメント タスクを簡単にするツールがあることを忘れないでください。

  • GhostDoc - コメントの継承とテンプレートのアドイン。
  • Sandcastle ヘルプ ファイル ビルダー- GUI を介して Sandcastle プロジェクトを編集し、(ビルドの自動化のために) コマンド ラインから実行でき、コードから派生していないヘルプ トピックの MAML を編集できます。(1.8.0.0 アルファ版は非常に安定しており、非常に改善されています。1.7.0.0 よりも約 1 か月使用しています)
于 2008-12-10T13:18:22.587 に答える
6

コメントが古くなっていることがよくあります。これは常に問題でした。私の経験則 : コメントを更新するために作業する必要があるほど、そのコメントはより早く陳腐化します。

XML コメントは、API 開発に最適です。これらは Intellisens とうまく連携し、HTML ヘルプ ドキュメントをすぐに生成できます。

しかし、これは無料ではありません: それらを維持するのは難しいでしょう (重要な例を見てください。私の言いたいことが理解できます)。結果として、XML コメントのレビューを必須チェックとしてコード レビューに追加する必要があり、このチェックはファイルが更新されるたびに実行する必要があります。

多くの非プライベート シンボル (非 API 開発の場合) は 1 つまたは 2 つのクラスでしか使用されず、これらのシンボルは多くの場合自明であるため、維持するのに費用がかかるため、次のような規則を強制することはありません。すべての非プライベート シンボルは XML コメントにする必要があります。これはやり過ぎであり、逆生産的です。あなたが得られるのは、私が多くの場所で見たものです: ほとんど空の XML コメントは、シンボル名に何も追加しません。そして、少し読みにくいコード...

通常の (API 以外の) コードでのコメントに関する非常に重要なガイドラインは、どのように記述すべきかではなく、何を含めるべきかということだと思います。多くの開発者は、まだ何を書けばよいかわかりません。例を使用してコメントする必要があることの説明は、単純な「すべての非プライベート シンボルに XML コメントを使用してください。」よりもコードに適しています。

于 2009-06-21T20:24:15.550 に答える
3

私はパブリッククラスとそれらのクラスのパブリック/保護されたメンバーを文書化します。

私はプライベートまたは内部メンバーまたは内部クラスを文書化しません。したがって、変数（フィールドを意味すると思います）はプライベートであるためです。

目的は、ソースコードにすぐにアクセスできない開発者向けのドキュメントを作成することです。

使用法が明らかでない例をいくつか配置するように努めてください。

于 2008-12-10T13:31:09.147 に答える
2

メソッド変数についてコメントすることはめったになく、フィールドについても同様にめったにコメントしません (通常、それらはプロパティによってカバーされているか、自動実装プロパティを使用している場合は単に存在しないためです)。

一般的に、すべての public/protected メンバーに意味のあるコメントを追加するように努めています。これは便利です。ビルド中に xml コメントを有効にすると、コメントがないという自動警告が表示されるからです。複雑さによっては、すべての詳細を記入しない場合があります。つまり、すべてのパラメーターが何をしなければならないかが 100% 明らかである場合(つまり、特別なロジックがなく、変数を解釈する論理的な方法が 1 つしかない場合)、私はそうするかもしれません。怠惰になり、パラメーターに関するコメントを追加しないでください。

しかし、私は確かに、メソッド、タイプ、プロパティなどが何を表しているか、または何をしているのかを説明しようとしています。

于 2008-12-10T13:18:55.660 に答える
0

Personally my opinion is to avoid commenting. Commenting is dangerous. Because in industry we always update code(because business & requirements are always changing), but vary rarely we update our comments. This may misguide the programmers.

于 2010-08-12T11:44:04.393 に答える
0

パブリックメソッド/プロパティなどをライブラリに文書化します。ビルドプロセスの一部として、NDocを使用してMSDNのようなWebリファレンスを作成します。クイックリファレンスとルックアップに非常に役立ちました。

また、Intellisenseにとっても、特に新しいチームメンバーの場合や、元の作成者がいなくなった場合に最適です。

私は、一般的に、コードは自明であるべきであることに同意します。私にとってのXMLドキュメントは、ソースを開いていない場合の参照とルックアップに関するものです。

于 2008-12-10T13:35:38.717 に答える