XML Comments: To Use or Not To Use?

Question

My co-workers rarely (if ever) use XML Comments when working on our software (I can't say I'm any better). I've recently seen the benefits of using them, but are they really worth it if the code they're documenting is written clearly (expressive/descriptive variable/function names, some in-line commenting)?

Thanks!

Answer 1

XML comments are usefull for generating documentation. If the code is clearly written then you shouldn't need comments to help you understand the code.

However documentation comments are usefull for the user of the classes because it (should) contain(s) a description of the class or methods functionality, not a description of the code.

Answer 2

XML comments are really useful for APIs even those used in a small group.

Answer 3

We find it useful, because vs automatically checks to make sure that certain comments are there. Also, anyone new coming into the organization that has used vs before knows how the comments work, and we don't have to explain a new system of commenting code. On occasion we have generated documentation from it, but really it's just easier for us to use it because it fills in a number of things for you (like some parameter tags etc.)

Answer 4

As far as internally facing code and comments, here's a post by Jeffery Palermo that I just read and have to agree with.

In summary: Lots of comments just reduces readability and help little, good comments can be very useful but increase the cost to maintain the software and can even cause major problems when they're not maintained and give false information. There's no substitute for well designed and named code.

Answer 5

Isn't there an annotation tag that is ignored functionally but can be processed by some XSLT to be turned directly into documentation? Comments are good (and I use them) but I think the value of the annotation tag and the direct transforming it can do outweigh the use of the comment as documentation. So in summary, use annotation tags for documentation to be read by others, use comments for notes to your self or 'behind the scenes' stuff (ie, 'OMG FIX THIS BEFORE THE WORLD EXPLODES!')