Question

StyleCop规则SA1600要求每个类型成员都有自己的文档标题。我认为这很合理，我喜欢这条规则。但是假设我们有以下层次结构：

/// <summary>
/// Documentation for interface ISomeModule.
/// </summary>
interface ISomeModule
{
    /// <summary>
    /// Documentation for DoA.
    /// </summary>
    void DoA();

    /// <summary>
    /// Documentation for DoB.
    /// </summary>
    void DoB();
}

/// <summary>
/// Documentation for StandardModule.
/// </summary>
class StandardModule : ISomeModule
{
    private readonly SomeCoolType _value;

    /// <summary>
    /// Documentation for constructor.
    /// </summary>
    public StandardModule(SomeCoolType value)
    {
        _value = value;
    }

    // SA1600 violation here!
    public void DoA()
    {
        // realisation of DoA().
    }

    // SA1600 violation here!
    public void DoB()
    {
        // realisation of DoB().
    }

    /// <summary>
    /// Documentation for MyOwnDoC.
    /// </summary>
    public void MyOwnDoC()
    {
        // realisation of MyOwnDoC().
    }
}

在这里，我完整地记录了接口成员DoA（）和DoB（），我们从接口文档中知道了这些方法的确切做法。 VS Intellisence也知道它，即使在类StandardModule中，我们也可以通过将鼠标悬停在这些方法上来看到方法的描述。因此没有必要将文档从接口复制到派生类。但StyleCop要求这样做。为什么？有人知道吗？

如果我们尝试解决这个问题，我们可以采用4种不同的方式：

1。从界面复制文档。 这里的问题是如果我们复制文档，如果接口行为发生变化，我们将遇到更新所有派生类中的文档的问题。

2。使用SuppressMessageAttribute抑制消息。 好吧，假设我们说“好的，我可以使用SuppressMessageAttribute”来抑制我不同意的这种违规行为。我在规则SA1600的前缀StandardModule和SuppressMessageAttribute之前。但是现在StyleCop停止检查StandardModule类中的文档头。我不想要它，因为我们有构造函数和其他一些方法。

第3。将班级划分为区域 我们可以将StandardModule类划分为2个区域，并仅在实现接口ISomeModule的部分上使用消息抑制。我认为所有部分都应放在一个文件中。我最喜欢这种方法（在＃4之后），但现在我们必须处理一个类的多个部分。

4。修改规则SA1600。是否可以自己实施规则SA1600，以便考虑是否在基类或接口中记录了类成员？（这里我不问我们是否可以为StyleCop编写自己的规则，我知道我们可以，但我的意思是StyleCop引擎是否可以检查某些成员是来自接口还是基类）。

在接口实现中解决SA1600问题的最佳方法是什么？

Answer 1

我从来没有想到这会是一个问题，因为我总是认为界面的声明的文档与实现的文档不同。这个界面。

我可能错了，但我很乐意学习。

我对你的问题的实际答案是：1）复制从界面翻译文档。

Answer 2

即将推出的StyleCop 4.4.1版本应该支持inheritdoc标签。如果您愿意使用支持此标记的文档生成工具（例如：Sandcastle或FiXml），那么您可能会找到一个可以解决您的问题的工作解决方案。

StyleCop SA1600规则和接口实现

2 个答案: