What are the virtues of using XML comments in .NET?

Question

I can\'t understand the virtues of using XML comments. I know they can be converted into nice documentation external to the code, but the same can be achieved with the much

Answer 1

The virtues of using XML comments in .NET

They are natively supported by the C# compiler and Visual Studio, providing a single location to document your API for use in printed, online, and intellisense documentation.

This article from MSDN magazine states the following:

In every project, there is someone who is not happy with the documentation. The team leads want more comments in the source, technical writers want more written information about the code design, Quality Assurance wants to see functional specifications, and so on. If all of those documents are actually written, you still have the battle of keeping all of them synchronized.

While the format is not necessarily ideal, XML documentation comments provide a rich syntax such that this can be achieved.

Why not support DOxygen in C# instead?

As for why the existing XML system was chosen over DOxygen, I would suspect this is primarily because DOxygen is released under the GPL which would mean Visual Studio and the C# compiler would also need to be released as such - something that Microsoft would no doubt not want to do considering the terms of the GPL.

Answer 2

1. The ide picks up the comments and shows them when using that method.
2. Everyone who programs C# is probably familiar with the XML commenting system. There's less to learn for a new hire.

I'm not saying that DOxygen isn't better, it's just that the xml commenting system is more familiar to everyone, and that goes a long way. It's just one less thing you have to train a new hire to do.

As far as leaving variables uncommented. What may be obvious to you, won't be to someone else (or to you 6 months later).

Ok now I think I see what you are asking.

1. Obfuscating comments. The color coding helps. Personally, I quickly scan past the grey text and only read what's green unless I need to read the xml text. (in my settings at least).

2. We have large monitors so we get more code on the screen in general. (It's cheaper to buy a large monitor than to retrain people generally). The other thing about this too, is that I bet you are only actively looking at one function at a time, so if that entire function fits on a page, you probably aren't suffering too much from not seeing more code. Now if the functions are long, then I could see that being a problem.

3. We put the summary comments on a single line when possible (assuming it isn't really large). That cuts down on the used space.

4. I don't know if DOxygen does this, but you can collapse the comments so they are out of the way.

Answer 3

You don't have to use them in your projects.

They are a standard that happens to be integrated into Visual Studio and if you use StyleCop they can be enforced. So this is the virtue here.

However, if you decide you want to use DOxygen then there's nothing stopping you. Just make sure you are consistent.

Answer 4

what I find even more mindblowing is the popularity of the ghostdoc plugin. If you can automatically generate a comment based on a method name, why have the comment at all?

Steve Yegge says that over commenting is the sign of a newbie programmer, I have a hard time disagreeing with him.

Answer 5

The primary job of XML documentation is not to generate documentation. It is to provide good IntelliSense info for the client of your class. Ship the generated .xml file along with your assembly.

Answer 6

There is not really a correct answer here imo. Neither system is "better" than the other in reality - they both do the same job in the end, which is allow you to generate code documentation.

The final output can be formatted in exactly the same way for each of them, and they do have pretty much the same functionality in terms of what labels etc they support, so its really down to personal choice here.

Personally I find XML comments to be much more human readable, much more logical and just plain easy to use - but that is with the added advantage of having visual studio automatically generate stubs for me to just fill in, and the excellent support it has for collapsing them so they don't take up lots of space on the screen. I am sure that someone who comes from a background editing in VI or some_other_IDE will have a different opinion, but there is no real advantage to either.

So I would say that really it depends on what IDE you are using and what you and your team are used to using.

Now if you are asking why Microsoft have chosen to integrate so tightly with XML commenting within Visual Studio, that is a different question. Most probably it is due to the facts that: it would be simpler for them to implement within VS (as they can re-use existing code to generate/read the comments and build intellisense etc), they have a trend for sticking to "standards" anyway (be it their own or industry ones), and also licensing reasons as mentioned by Jeff.

Just to add that the product Microsoft is using within VS is called "Sandcastle", which is an in-house XML doc generation tool. It has its own wiki page @ http://docproject.codeplex.com/Wikipage