I was just running style cop against some of my code and got a few:
SA1600: The field must have a documentation header.
Now don't get me wrong I like style cop, it's great when you work on a project with more then one person but this rule seems a bit excessive to me. Why would you want to add:
/// <summary> /// blah blah blah /// </summary>
to the top of every variable. I'm pretty sure that I remember someone saying(Martin Fowler, Kent Beck..can't really remember ATM) that comment should say "why" not "what" and I really can't see how you can explain why on a variable.
I also find code that has comments on every variable harder to read because all you see is fluff.
My thoughts are if you have to explain what every variable is then you are really failing in terms of naming.
Does anyone else find commenting variables a bit of a code smell or is it just me.
This is quite an old post but came across it while searching for a solution to this issue myself, so though I would offer a solution.
If you open your Settings.StyleCop file in the rules editor, select the Documentation Rules node, then in the Detailed settings section on the right de-select the Include fields option. Now you will no longer be required to document fields.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With