StyleCop SA1600规则和接口实现

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”来抑制这种我不同意的违规行为。我在 StandardModule 类前面添加了规则 SA1600 的 SuppressMessageAttribute。但现在 StyleCop 完全停止检查 StandardModule 类中的文档标题。我不想要它，因为我们有构造函数和其他一些方法。

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

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

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

Answer 1

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

Answer 2

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

我可能错了，但我很高兴学习。

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

Answer 3

我只是使用 /// 来实现这一点。 当它只是接口中的方法时，我也倾向于在公共方法上使用它。像这样的单一方法往往具有与其接口完全相同的解释。 （该接口存在的唯一原因是为了该方法）。