フィールドにはドキュメントヘッダーが必要です-スタイル警官-コードの臭い？
私は自分のコードのいくつかに対してスタイル警官を実行していて、いくつかを取得しました：
SA1600: The field must have a documentation header.
誤解しないでください。私はスタイル警官が好きです。複数の人がいるプロジェクトで作業する場合は素晴らしいですが、このルールは私には少し過剰に思えます。なぜ追加したいのですか：
/// <summary>
/// blah blah blah
/// </summary>
すべての変数の先頭に。コメントは「何」ではなく「なぜ」と言うべきだと誰かが言ったことを覚えていると確信しています（マーティン・ファウラー、ケント・ベック..ATMを本当に覚えていません）。変数。
また、すべての変数にコメントが含まれているコードは、綿毛だけが表示されるため、読みにくくなっています。
私の考えでは、すべての変数が何であるかを説明する必要がある場合は、名前付けの点で本当に失敗しています。
他の誰かがコメント変数を少しコードの臭いに感じますか、それとも私だけですか？.
変数にコメントすることが常にコードの臭いであるとは言いません（そして、それはあなたが言っていることのようにも聞こえません）。私は、すべての変数にコメントすることは、少なくとも毎回過度であり、おそらく名前の付け方が悪いことを示していることに同意します。実際、anyコメントはコードの臭いであり、説明的な名前と短いルーチンはより読みやすく、コードが変更されたがコメントが更新されていない状況を防ぐと主張する人もいます（これは確かにいくつかのレガシーコードベースで私を噛みました）。それほど遠くまでは行かないと思いますが、特別な説明なしに自明のコードを書くことができれば、それは好ましいように思われます。
そうそう、基本的にあなたが言ったこと。
これはかなり古い投稿ですが、この問題の解決策を自分で探しているときに出くわしたので、解決策を提供します。
ルールエディタでSettings.StyleCopファイルを開く場合は、ドキュメントルールノードを選択してから、右側の詳細設定セクションを選択します。 フィールドを含めるオプションを選択します。これで、フィールドを文書化する必要がなくなります。
XMLコメントは、他のコメントとは少し異なります。
正しく設定すると、Visual Studioのツールチップに表示され、SandCastleで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?
上記の機能を使用したくない場合は、StyleCopルールをオフにしてください。
完全に同意し、StyleCopで最初にオフにしました。説明が必要な場合は、説明が必要な方法で名前を付けており、コードの作成に失敗しています 自己文書化 。
まだこの問題に遭遇している人のために、この投稿 how-to-change-a-stylecop-rule は実際に完璧な答えを持っています。
試してみてください GhosDoc は、アプリケーションのすべてのコードメンバーのドキュメントを自動化する簡単な方法です。インストールするだけで、メンバーを右クリックしてドキュメントを選択できます。
ここでの正解は「状況次第」だと思います。変数がstatic/constとマークされている「理由」、または変数の内容に対するビジネスロジック/制限を確実に説明できます。そうは言っても、すべての変数コメントを見ると読みやすさが妨げられ、標準または不適切な命名に従うことを盲目的に示す可能性があることに同意します。