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 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.