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

I think code comments are very important, especially on public facing methods and properties. People may mean well when they say their code is descriptive and maybe it is, but think of the new guy who looks at this:

Linker.Extract(IpoValidator validator, MeanDexIndicator Indicator)

Unless he understands the context of the method he may not figure out its purpose. The main issue people seem to have with comments are they are not very helpful. This is because people write bad comments. You should talk about what's going on not what it is. I can see that method is an extraction method, so comments like:

 <Summary>Extracts The Fumble <\Summary>

Are a waste of energy. The following is better:

 <Summary>
 The Fumble needs to be extracted before the bopper can be used. In order for 
 extraction to work a validator and indicator need to be provided. Once extracted 
 the bopper is available in the property Linker.Bopper. On fail this 
 method will raise the CrappedOutException.
 </Summary>

See the difference?

I tend to use only summaries params and returns as they all show in intellisense, everything else like remarks and may be a waste of time as they are not always shown.

As for the guy who refuses to update his comments after changing something. Code reviews should catch this. Personally I use xml comments on private methods and props two but that one is personal choice. On public facing methods and properties? I is non optional.

Answer 3

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

Answer 4

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 5

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 6

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!')