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

Question

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.

Answer 1

I think the correct answer here is "it depends." You can certainly explain the "why" of a variable being marked static/const, or business logic/restrictions on the variable's contents. Having said that, I agree that seeing every variable comment impedes readability and can indicate blindly following a standard or improper naming.

Answer 2

I wouldn't say that commenting a variable is always a code smell (and it doesn't sound like that's what you're saying, either). I do agree that commenting every single variable, every single time is at the very least excessive, and possibly indicative of poor naming. In fact, some would argue that any comment is a code smell, and that descriptive names and short routines are more readable and prevent the situation where code has been changed, but the comments haven't been updated (which has certainly bitten me in a few legacy code bases). I don't think I'd take it quite that far, but if you can write code that is self-explanatory without extra explanation, that does seem preferable.

So yeah, basically what you said.

Answer 3

XML Comments are slightly different than other comments.

If you set things up correctly, you can have them appear in tool tips in Visual Studio AND use them to create MSDN style documentation with Sand Castle. I think they should tell you what the thingy is doing when you don't have access to the source code.

The point is that these comments can appear without the source code that they are commenting. They should be helpful to another devloper who can't see your code and could care less how you are doing things.

I don't know about the "Cop" tool you are using, but it would be nice to have a way of signaling the tool that intend to leave a param blank. So:

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

I have worked on projects where we have to fill everything in and we get things like:

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

If you don't want to use the features above, go ahead turn off the Style Cop rule.

Answer 4

Totally agree and the first thing I turned off in StyleCop. If you need to explain it, you have named it in a fashion which needs explanation and have failed in making the code self documenting.

Answer 5

You should try GhosDoc is an easy way to have documentation automated for every code member on your application. Just install it, right click on the member and select document this!