コードの一部に対してスタイル警官を実行していたところ、いくつか得られました。
SA1600: The field must have a documentation header.
誤解しないでほしいのですが、私はスタイル コップが好きです。複数の人と一緒にプロジェクトに取り組むときは素晴らしいのですが、このルールは私には少し過剰に思えます。追加する理由:
/// <summary>
/// blah blah blah
/// </summary>
すべての変数の先頭に。誰かが (Martin Fowler, Kent Beck.. ATM はよく覚えていない) コメントは「何」ではなく「なぜ」と言うべきだと言ったことを覚えていると確信しています。変数。
また、すべての変数にコメントがあるコードは読みにくいと思います。
私の考えでは、すべての変数が何であるかを説明する必要がある場合、名前付けに関しては本当に失敗しています。
他の誰かがコメント変数にコードの匂いを感じているのですか、それとも私だけですか?
これはかなり古い投稿ですが、この問題の解決策を自分で探しているときに見つけたので、解決策を提供します.
ルール エディターでSettings.StyleCopファイルを開く場合は、[ドキュメント ルール]ノードを選択し、右側の [詳細設定] セクションで [フィールドを含める] オプションの選択を解除します。これで、フィールドを文書化する必要がなくなりました。
変数にコメントすることが常にコードのにおいだとは言いません (また、あなたが言っていることのようにも聞こえません)。すべての変数を毎回コメントすることは、少なくとも過度であり、おそらく不適切な命名を示していることに同意します。実際、コメントはコードの匂いであり、説明的な名前と短いルーチンは読みやすく、コードが変更されたのにコメントが更新されていないという状況を防ぐと主張する人もいます (これは確かに私を悩ませていました)。いくつかのレガシー コード ベース)。私はそこまでとは思いませんが、余分な説明がなくても自明なコードを書けるなら、それが望ましいと思われます。
ええ、基本的にあなたが言ったこと。
XML コメントは、他のコメントとは少し異なります。
正しく設定すれば、Visual Studio のツール ヒントにそれらを表示し、それらを使用して Sand Castle で MSDN スタイルのドキュメントを作成できます。ソースコードにアクセスできないときに、何をしているのかを教えてくれるはずです。
ポイントは、これらのコメントは、コメントしているソース コードなしで表示できるということです。それらは、あなたのコードを見ることができず、あなたがどのようにやっているのかをあまり気にしない別の開発者に役立つはずです.
あなたが使用している「Cop」ツールについては知りませんが、パラメータを空白のままにするツールにシグナルを送る方法があればいいと思います. そう：
/// <param name="fubar"></param> // Haven't gotten around to it
/// <param name="portNumber" /> // I intend this parameter to have no help
私はすべてを埋めなければならないプロジェクトに取り組んでおり、次のようなものが得られます。
/// <param name="portNumber">The Port Number</param> // What else could it be?
上記の機能を使用したくない場合は、Style Cop ルールをオフにしてください。
まだこの問題に遭遇している人には、この投稿how-to-change-a-stylecop-ruleに実際に完璧な答えがあります.
GhosDocは、アプリケーションのすべてのコード メンバーのドキュメントを自動化する簡単な方法です。インストールするだけで、メンバーを右クリックしてドキュメントを選択してください。
ここでの正解は「場合による」だと思います。変数が static/const とマークされている「理由」、または変数の内容に対するビジネス ロジック/制限を確実に説明できます。そうは言っても、すべての可変コメントを見ると読みやすさが妨げられ、標準的または不適切な命名にやみくもに従っていることを示している可能性があることに同意します。