[Deestan]

Not so much strange, as Twilight Zone-esque insane: All methods and properties must be commented with XML.

Sounds like a good idea, until you see how this turns terse and readable code into a bag of chatty noise. Basically this:

    public enum ConnectionState {
        Disconnected, Connecting, Connected
    }

Was not compliant ("There's no comments! It's not readable!"), while this:

    /// <summary>
    /// The Connection State.
    /// </summary>
    public enum ConnectionState {
        /// <summary>
        /// The Connected State.
        /// </summary>
        Connected,

        /// <summary>
        /// The Disconnected State.
        /// </summary>
        Disconnected,

        /// <summary>
        /// The Connecting State.
        /// </summary>
        Connecting
    }

Was considered Compliant and Good. This example has not been simplified, by the way.

[afandian]

I too was forced to do that. I too found it ridiculous. But not for long. There was a utility for generating the documentation strings (it got them right most of the time) and there's a lot to be said for consistency, even if it produces the occasional pointless-looking artefact. The reason this requirement is in the C# style guidelines is because it gives a consistent way of commenting and, of course, allows extraction of documentation and intellisense. I am no drone by any means, but this isn't so insane if you give it some thought.

[Deestan]

There wasn't "the occasional pointless-looking artifact"; I would have been fine with that. 95% of all code comments merely mimicked the type signature. People were using Visual Studio plugins to autogenerate the "documentation". Pressing SHIFT+ALT+J (or something) would read the function name and type signature and regurgutate some XML doc matching it.

> allows extraction of documentation and intellisense.

These already give you type signature and function name. If intellisense already gives you "bool isValid", what possible gains do you get from an extra "boolean value indicating whether the value is valid"?

> I am no drone by any means, but this isn't so insane if you give it some thought.

Trust me, I have given it plenty of thought. Some conclusions from these thoughts:

- Code comments that merely mimic the type signature add nothing. Not for readability, not for intellisense, not for documentation extraction.

- They increase the signal-to-noise ratio of the code immensely, making it harder to read. Comments with actual useful information will now drown in the sea of drivel.

- Fuck it, I'm not working here anymore.

The main fallacy here is that More Process and More Rules can make bad programmers write good code.

[afandian]

Fair enough. I found that in a collaborative environment (people making and sharing code) the style guidelines had a net positive effect (and believe me, my first gut reaction was along the 'this is insane' lines). As process go, the degree of automation and strict automatic enforcement (and fixing) of rules felt lightweight after a bit.

We're neither of us going to convince the other, I just thought I'd add a datapoint. FWIW I now write Python and although PEP8 isn't as hard-line, I think it similarly does a lot of good.

[bruceboughton]

>> Code comments that merely mimic the type signature add nothing. Not for readability, not for intellisense, not for documentation extraction.

Agreed. In fact, over time, they are likely to be not merely useless but harmful as the API signature evolves over time, unless the developer also updates the (pointless) comment.

[bunderbunder]

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.

[bruceboughton]

If you're using auto-doc-generation, there is no information in the generated documentation that isn't in the API.

[afandian]

Not sure what you mean by "the API". You mean C# interfaces? And what about Intellisense?

[bruceboughton]

Intellisense is generated from the types, methods, fields, and properties (the API). If there is XML documentation it is added to Intellisense popup. If the documentation is auto-generated from the code structure then it will add nothing that is not already present in the Intellisense.

[afandian]

Sure. Like I said, there are some cases where the textual documentation adds nothing to the stuff it's derived from. And there are lots of cases where documentation is useful (I'm assuming you're not saying there should be no documentation). I think that it's worth having consistency of rules (with some redundancy) over patchy documentation. I'm not trying to convince anyone, just a datapoint that I don't think it's "insane".

[ygra]

The original point was that auto-generated documentation comments contain nothing that isn't already there in the public interface. Since it tends to look like

    /**
     * Foos the bar.
     *
     * @param bar The bar.
     */
    public void fooBar(Bar bar) { ... }

The problem with this kind is that the compiler can no longer warn about a missing documentation comment because from its side all looks nice and well – except that there is zero information in that documentation.

My boss once did that to our entire codebase, adding auto-generated doc comments where there weren't any. Sure, my warning count reached a new low, but documentation quality suffered for months.

[wladimir]

But why XML? IMO the doxygen / javadoc style of comments makes for much less pollution. XML is not a good format for text that is to be read by humans.

[ygra]

Javadoc is tied so closely to HTML that any output format other than HTML is quite difficult to achieve.

[afandian]

It's been a while so I'm a bit rusty. But for most comments it would just be a start and end tag. You could also reference other types, XHTML style.