Question

I work in a team where we use extensive ruleset in StyleCop and I am wondering what are the thoughts on the general point where such a tool stops being useful and starts becomes annoying. We also use GhostDoc so code is riddled with XML comments which make the code much harder to read and thus review. I have no problem with XML comments and find them very useful in places but are they really needed on every field and property?

We have the admirable goal of “each project must have 0 Warnings when built” but surely this goal needs to be against a reasonable StyleCop ruleset otherwise valuable time is wasted in “fixing” the cause of the StyleCop warnings.

What are the thoughts on this?

EDIT
I’m now actually wondering what is the argument for a tool like stylecop AT ALL? Why not ditch it and let sensible coding standards and good code reviews take care of the rest? Especially in a good competent team? Surely then the task of getting 0 Warnings would actually add value as all Warnings would be relevant.

I think the only advantage of GhostDoc is it saves you a vital few seconds in writing an XML comment from scratch. I don’t think you should accept the generated comment without editing it – which is counter-productive maybe.

Here’s a combination of a Stylecop rule (SA1642: ConstructorSummaryDocumentationMustBeginWithStandardText) being met by GhostDoc generated xml comment – does either add any value at the end of the day?

    /// <summary>
    /// Initializes a new instance of the <see cref="SomeCustomType"/> class.
    /// </summary>
    /// <param name="someParameter">The someParameter.</param>
    public SomeCustomType(string someParameter)
    {
    }

Answer 1

This is more of a rant than a question, I think, but I agree with you that:

• over-enforced style rules are a bad thing.

Whilst there should obviously be guidelines for source code formatting, over-prescriptive unbreakable rules lead to unpleasant corner cases. Sticking strictly to the rules in all cases can generate unreadably messy or over-wrapped code.

Coding is a variety of writing, and as such Orwell’s Bonus Rule—“Break any of these rules sooner than saying anything outright barbarous​”—needs to apply to coding style guides too.

I am sceptical that automated style enforcement is a good idea, in a team of competent programmers who can set and understand style guides. Automated lints are useful for catching accidental mistakes, but if applied with highly prescriptive laws for code formatting they cannot take account of Orwell’s rule. With a strong ruleset, this may force you to write less-maintainable code under the guise of maintainability.

If you’ve got less-competent coders in your team, whose output is a jumble unless forced into style, then enforcement might be a good idea. (But then you’ve probably got bigger problems!)

• automated comments are a very bad thing

I hadn’t seen GhostDoc before, but I’m actually a little bit shocked.

The very example on their own front page:

/// <summary>
///     Determines the size of the page buffer.
/// </summary>
/// <param name="initialPageBufferSize">
///     Initial size of the page buffer.
/// </param>
/// <returns></returns>
public int determineBufferSize(int initialPageBufferSize) {

is almost the canonical example of a Bad Comment, adding absolutely zero insight into the code it documents. This is absolutely worse than no comment-doc.

All the in-source-doc schemas that followed Javadoc are a little bit suspect at times, since they clutter the source code with material that’s often aimed at end-users—a quite different audience to those reading the code. But this is the absolute pits. I can’t imagine who thought this was a good idea.