|
|
|
|
|
by bunderbunder
4938 days ago
|
|
If you're using a tool like Sandcastle to generate separate documentation, it won't produce decent output for elements that don't have XML comments. For that reason, while I also find those comments to be irritating I'm still in favor of a requirement that they be present for anything that's meant to be consumed by third parties. Also, it sounds like some of the problem you're describing could have as much to do with people being slackers about the rule, than the rule itself. Someone should be taking charge of making sure these XML comments are useful, high-quality comments. There's almost always more information that should be provided beyond re-iterating the element's name. For example, the XML comments for a property named "IsValid" should reference some documentation of exactly what defines a valid state for that class. Numeric properties should very likely have notes about what unit denominates them. At the absolute least, make sure that every property's descriptive comment starts with "Gets", "Sets", or "Gets or sets". Just to get in ahead of an obvious answer, let me also go ahead and say that if this is a situation where it's reasonable to tell users that they should just RTFS, then obviously this is a situation where there's not necessarily any need to require XML comments in the first place. But if you do need to require XML comments, you should also be requiring proper XML comments. |
|