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"来抑制我不同意的这种违规行为.我在规则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),您可能会有一个可以解决您的问题的工作解决方案.