Should I always use xml comments?

[MrNorth]

Hi!

I need a second (or third) opinion about the xml comments you can add with ''' or /// in visual studio. Usually I just comment on stuff that needs explanation, and I always comment classes with some info about what it is for. But methods, properties etc only when absolutely needed.

Today, a guy at the company I work for stated that I have checked in some code that doesn't adhere to company guidelines (my second week here). I asked him whats the problem, and he said I forgot to add the xml comments on lots of properties, methods etc that generated lots of warnings in their build system. I told him, what if the method doesn't need commenting, because it is obvious what it does, then he said that I should put the xml comment there anyway but leave everything blank (just to get rid of the build warning)

Is this really the "correct" way to do it? I mean isn't it better to add comments when really needed? Or is there any difference between regular code comments and these xml comments? I come from a C++ background and there we do things differentlly...

kind regards
Henrik

[MattP]

If the company guidelines tell you to add the xml comments then you add them. It doesn't really take that long to fill out the xml comments especially on self documenting methods.

Of course if you feel like your abundance of experience with the company will let you get away with telling them to shove their policy somewhere then it's up to you.

[Joacim Andersson]

We have had many of these kind of discussions here before... When should you comment and when not to... I want to start this discussion (before I feel the need to move this into another forum) with when I feel XML comments are necessary: Whenever you build libraries and APIs that are used by others then XML comments are great! You see them in tooltips together with intellisence.

Now, in your specific case the company you work at has obviously put this into a rule that you need to follow to be able to check anything into your source control system. Having such a rule is fine if you're only writing libraries that should be used by others. However if you can still leave them empty then that is just a simple way to work-around the rules already set in stone by your company. Doing that is still bad and the fact that they think that is OK is even worse. What that tells me is that if they think that there are cases when the rule can be ignored then why even have it in the first place?

Tell people what the rules are: Use XML comments when they should be used and if you're caught not doing so we're going to spank you in public.... That is actually much better than enforcing a rule that people will ignore when they feel like it by creating empty XML comments.

However, in the end, you have to work with these guys so put up a good argument of what you think is right and wrong but then just do what they tell you regardless of how stupid it is.

[Shaggy Hiker]

Every company has some weird policies. Some aid in productivity, some do not. I had a friend who worked at a company where it was customary to start drinking after noon, plus smoking a bit of weed for those who were into that. They are an artistic company, so it's a bit hard to say what that would do to their productivity, but it sounded like most were bombed and stoned by the end of each work day.

You just have to live with what quirks there are. I love where I work, but it has quirks, too.

[Joacim Andersson]

@Shaggy: There are actually studies that show that smoking pot will boost your creativity to the extend that during 15 minutes you can be able to create something that would otherwise take you almost an hour in a sober state.

The problem is however that those 15 minutes a day of creative time is the most you can get from a person that is high on pot. So compare that with a sober person that are creative during 8 hours a day. Who do you want to put your money on?