XMLコメントのヒントのC#プログラミング［定休日]

Question

良い朝、昼、夕方や夜間によってタイムゾーン).

これは一般人ではXMLコメント内のC#.いて非常に大きめにカットコメント私のプログラム、普通に使っていたのにデフォルト値が設定され変数/財産/法namerのおまかせのコードなどがこれを雄弁に物語っている。い書きのコメントについて知っておきましょ符号化るものではなく、一部だテルのすぐ近くは飲食面では貧弱。

やっていたのは一部についての本を読むXMLコメントです。ネど、ヘルプファイルをビルダーにcodeplexという道をしたい、ということはあまりの文書は私のコードを生成でも、文書をする機会のある方にとって掘りの私にはコードが無いんです。

私の質問は基準とのコンベンションあのガイド"良い"XMLコメント?だコメント毎の変動がですか？毎方法は？私は基本的に見るためにどんなコーディネートに良いコメントするめどが掃除の行き届いた気持ちの良い文書ではその他のプログラマーな呪私の名前が終わる私のコードです。

過ごしやすそうなきれいなアドバイスやご提案 スコットVercuski

Answer 1

個人的には、まず全ての公的な保護方法はXMLコメントです。ものごとを行頭に付けただけではなくユーザーの助けます。過去にも含まれまでに私費外scoped宣言がないの雰囲気を感じることができ100％の必要などの方法が短いため、ポイント。

ることを忘れないでくださいツールが使XMLコメントを作り

• GhostDoc -コメントの継承と孔を追加します。
• 設ヘルプファイルをビルダー -編集の設事業をGUIで走行可能なコマンドラインから(ビルド自動化）、編集できるMAML助論から導かれるものではない。（1.8.0.0アルファ版が非常に安定した非常に改善します。も愛用頂いているシステムで一ヶ月ん1.7.0.0)

Answer 2

コメントは非常にしばしば時代遅れです。これは常に問題がありました。私の経験則:の制作に必要なもの更新のコメントを高速化するコメントする互換性のために残されています。

XMLコメントによるAPIの開発など。彼らの作品と良くIntellisensびたいと思っていまを生成するドキュメントを編集するには、ヘルプドキュメントできます。

これはフリーではありません:の維持としておこなわれたものであるハードは自明ではない、まう）、その傾向がありますが古います。その結果、 見直しはXMLコメントを追加する必要がありますコードレビューとして必須チェック このチェックは毎時ファイルが更新されます。

ものであ維持、多くの民間のシンボルを非APIの開発）においてのみ使用する1又は2の授業は、これらのsymbolesが自己説明しな実施を原則という毎非民間のシンボルはXMLりました。 これを失わせないアイテムとconterproductive.かどうかを取り付ける際に使用します。ンネポムセノ教会などの見所も、多くの場所:近い空のXMLコメント追加なしのsymboleの名前です。コードとほんの少し下が読む...

ことになると思い 非常に 重要なガイドラインは約コメントが通常（API）コードすべきでない約 どのように書き が約 何をすべきかを含む.多くの開発者が知らない 何 に書き出します。の説明をすべきは、事例をもとに、カスタマーサポート/よくeメールアドレスだけではな分野:"の使用にXMLコメント毎の非個人symbole.".

Answer 3

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

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

目的は、ソースコードへの容易なアクセスを持っていない開発者のためのいくつかのドキュメントを作成することです。

の使用が明らかにされていませんいくつかの例を配置に努めるます。

Answer 4

私は非常にまれメソッド変数にコメントしない、と（彼らは通常、プロパティによって覆われている、または自動実装プロパティを使用している場合は、単に存在しないので）均等めったにフィールドません。

は、一般的に私は、あなたが、ビルド時に、XMLコメントをオンにした場合、あなたはコメントを逃すための自動警告を取得するので、便利であるすべてのパブリック/保護されたメンバーに意味のあるコメントを追加するのは難しいしてみてください。複雑さに応じて、私はすべての詳細を記入していない可能性があります - すべてのパラメータがを持っているものを100％明白である場合、すなわち行う（つまり、特別なロジックが存在しない、と解釈するだけで1論理的な方法があります変数が）、私は可能性がありますの怠惰を取得し、パラメータに関するコメントを追加しません。

を

しかし、私は確かに/表して何をすべきかの方法、種類、性質などを説明してみます。

Answer 5

私たちは、図書館のパブリックメソッド/プロパティ/などを文書化。ビルドプロセスの一環として、我々はMSDNのようなウェブの参照を作成するためにされたNdocを使用しています。これは、クイックリファレンスとルックアップのために非常に役立っています。

それはあなたがオリジナルの著者がなくなったとき、言ったように、特に新しいチームメンバーと、また、インテリセンスのために素晴らしいことだか。

私はコードは、一般的には、自明でなければならないことに同意するものとします。 XMLのdocumentionが、私には、あなたがオープンソースを持っていないときに、参照および検索の詳細についてです。

Answer 6

個人的に私の意見をコメントしないようにすることです。コメントは危険です。業界では、我々は常に（ビジネス＆要件は常に変化しているため）コードを更新しますが、異なるため、めったに私たちは私たちのコメントを更新しません。これは、プログラマをmisguideあります。