フィールドにはドキュメントヘッダーが必要です - スタイルコピ - コードの匂い？

Question

私はちょうど私のコードの一部に対してスタイル警官を実行しているし、いくつか得た：

SA1600: The field must have a documentation header. 

は、今私はスタイルの警官が好き誤解しないでくださいあなたはもっとして1人でのプロジェクトで作業する場合、それは素晴らしいことだしこのルールは私には少し過度のようです。なぜすべての変数の先頭に：

/// <summary> 
    /// blah blah blah 
    /// </summary> 

を追加しますか？私は、誰かが「マーティン・ファウラー、ケント・ベックはATMを本当に覚えていない」と言っている人を覚えていると確信しています。そのコメントはなぜ「何」ではないと言わなければならないのですか？変数。

また、すべての変数にコメントが含まれているコードは、わかりやすく表示されています。

あなたは、すべての変数が何であるかを説明しなければならない場合は、名前の面で本当に失敗していると思います。

他に誰かがコードの臭いのコメント変数を見つけたり、それは私だけです。

Answer 1

私は、変数にコメントするのは常にコードの匂いであるとは言いません（そして、あなたが言っているようには聞こえません）。私はすべての単一の変数にコメントすることに同意します。毎回の時間は、少なくとも過度であり、おそらく貧弱な命名を示す可能性があります。実際には、のいずれかがのコメントはコードの匂いであり、その記述的な名前と短いルーチンは読みやすく、コードが変更されているがコメントが更新されていないいくつかのレガシーコードベースで）。私はそれほど遠くはないと思っていますが、余分な説明がなくてもわかりやすいコードを書くことができれば、それは望ましいようです。

だから、基本的にあなたが言ったこと。

Answer 2

ここでの正解は「それは依存している」と思います。静的/静的とマークされている変数の「理由」、または変数の内容に関するビジネスロジック/制限については、確かに説明できます。言いましたが、私はすべての変数のコメントを見れば、読みやすさが妨げられ、標準または不適切な命名に従って盲目的に表示されることに同意します。

Answer 3

XMLコメントは、他のコメントと若干異なります。

正しく設定した場合は、Visual Studioのツールヒントに表示され、それらを使用してSand CastleのMSDNスタイルのドキュメントを作成できます。ソースコードにアクセスできないときに何をしているのかを教えてください。

これらのコメントは、コメントしているソースコードなしで表示できるということです。彼らはあなたのコードを見ることができず、あなたが物事をどのようにしているかを気にすることができない別の逸脱者に役立つはずです。

あなたが使用している "Cop"ツールについてはわかりませんが、パラメータを空白のままにしておくツールを通知する方法があると良いでしょう。だから、：オフに先に行く、あなたは上記の機能を使用しない場合は

/// <param name="portNumber">The Port Number</param> // What else could it be? 

：

/// <param name="fubar"></param> // Haven't gotten around to it 
    /// <param name="portNumber" /> // I intend this parameter to have no help 

私たちはですべてを埋めるために持っていると私たちはのようなものを取得するプロジェクトに取り組んできましたStyle Copルール。

Answer 4

完全に同意し、私はStyleCopで最初にオフにしました。説明が必要な場合は、説明が必要な形式で名前を付け、コードの作成に失敗しましたself documenting。

Answer 5

試してみてください。GhosDocは、アプリケーションのすべてのコードメンバーに対して自動化されたドキュメントを簡単に作成する方法です。インストールするだけで、メンバーを右クリックしてドキュメントを選択してください！

Answer 6

これはかなり古い投稿ですが、この問題の解決策を自分自身で探している間に出てきました。だから私は解決策を提案します。

あなたはルールエディタでSettings.StyleCopファイルを開くと、ドキュメントの規則にノードを選択し、[詳細設定で右デ選択上セクションでは、フィールドオプションを含めます。これで、フィールドを文書化する必要がなくなりました。

Answer 7

まだこの問題に遭遇している人にとっては、この投稿how-to-change-a-stylecop-ruleには実際には完璧な答えがあります。