XMLコメント：使用するかしないか

Question

同僚が私たちのソフトウェアに取り組んでいるとき、XMLコメントを使用することはめったにありません（私はこれ以上優れているとは言えません）。私は最近それらを使用する利点を見てきましたが、文書化するコードが明確に書かれている場合（表現的/説明的な変数/関数名、いくつかのインラインコメント）、本当に価値がありますか？

ありがとう！

Answer 1

XMLコメントは、ドキュメントの生成に役立ちます。コードが明確に書かれている場合、コードを理解するのに役立つコメントは必要ありません。

ただし、ドキュメントのコメントは、コードの説明ではなく、クラスまたはメソッドの機能の説明を含む必要があるため、クラスのユーザーにとって有用です。

Answer 2

コードのコメントは、特に公開されているメソッドやプロパティでは非常に重要だと思います。自分のコードが記述的であり、おそらくそうであると言うとき、人々は良い意味を持つかもしれませんが、これを見る新しい男のことを考えてください：

Linker.Extract(IpoValidator validator, MeanDexIndicator Indicator)

メソッドのコンテキストを理解しない限り、その目的を理解できない可能性があります。人々がコメントに関して抱えている主な問題は、あまり役に立たないということです。これは、人々が悪いコメントを書くためです。何が起こっているのかではなく、何が起こっているのかを話すべきです。このメソッドは抽出メソッドであることがわかります。そのため、次のようなコメントがあります。

 <Summary>Extracts The Fumble <\Summary>

エネルギーの無駄遣いです。以下の方が優れています。

 <Summary>
 The Fumble needs to be extracted before the bopper can be used. In order for 
 extraction to work a validator and indicator need to be provided. Once extracted 
 the bopper is available in the property Linker.Bopper. On fail this 
 method will raise the CrappedOutException.
 </Summary>

違いを参照してください

要約パラメータとリターンのみを使用する傾向があり、それらはすべてインテリセンスで表示されるため、他のすべては発言のようなものであり、常に表示されるわけではないので時間の無駄になる場合があります。

何かを変更した後にコメントを更新することを拒否する人については。コードレビューでこれをキャッチする必要があります。個人的に私はプライベートメソッドと小道具2にXMLコメントを使用していますが、それは個人的な選択です。公開されているメソッドとプロパティについて？私はオプションではありません。

Answer 3

XMLコメントは、小さなグループで使用されるものであっても、APIに非常に役立ちます。

Answer 4

vsは、特定のコメントがあるかどうかを自動的にチェックするため、便利です。また、以前に使用したことのある組織に新しく参入した人は、コメントがどのように機能するかを知っているので、コードをコメントする新しいシステムを説明する必要はありません。ときどきドキュメントを生成しましたが、実際には（パラメータータグなどの）多くのことを埋めるため、実際に使用する方が簡単です。

Answer 5

内部で直面しているコードとコメントに関する限り、こちらの投稿 Jeffery Palermo が読み、同意する必要があります。

要約：多くのコメントは読みやすさを低下させ、ほとんど役に立たないため、良いコメントは非常に便利ですが、ソフトウェアを維持するためのコストが増加し、維持されていない場合に重大な問題を引き起こし、誤った情報を提供することさえあります。適切に設計された名前付きコードに代わるものはありません。

Answer 6

機能的には無視されますが、XSLTで処理してドキュメントに直接変換できる注釈タグはありませんか？コメントは良い（そして私はそれを使用する）が、注釈タグの価値とそれを直接変換することは、文書としてのコメントの使用よりも重要だと思う。要約すると、他の人が読めるようにドキュメントに注釈タグを使用し、自分へのメモや「舞台裏」のものへのコメントにコメントを使用します（つまり、「OMG FIX THIS BEFORE THE WORLD EXPLODES！」