Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

The field must have a documentation header - Style Cop - Code smell?

Tags:

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.

like image 789
Nathan W Avatar asked Jul 07 '09 23:07

Nathan W


1 Answers

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.

like image 196
Nixus Avatar answered Dec 08 '22 12:12

Nixus