StyleCop SA1600规则和接口实现

StyleCop规则SA1600要求每个类型的成员都有自己的文档头。我认为这很合理，我喜欢这个规则。但是，假设我们有以下层次：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，我在SuppressMessageAttribute前面添加了StandardModule类。但是现在StyleCop停止检查类StandardModule中的文档标题。我不想要它，因为我们有构造函数和其他一些方法。

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

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

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

来源

2011-01-20 Dmitry Lobanov

对于一个写得很好的质量问题+1。 – 2012-03-24 18:47:38

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

来源

2011-01-20 12:56:47

它永远不会发生，我认为这将是一个问题，因为我一直认为一个接口作为东西比此接口的实施的文件不同的声明的文档。

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

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

来源

2011-01-20 11:50:52 Filburt

然后我需要保持类文档与接口文档同步，从而在更改和编写代码的过程中再增加一步。我认为文档加倍是双倍的，如果我们试图避免代码翻倍，为什么我们要在其他文档中加倍翻译。加倍是邪恶:) – 2011-01-20 12:21:41

@Dmitry我完全同意，加倍是邪恶的。但改变界面应该会导致对文档的更新，就像更改实现一样。我认为第一个是记录第二个应该如何发生的应该发生的事情。如果你强烈反对重复自己，并按照罗伯特“鲍勃叔叔”马丁的“清洁守则”的思路思考，你最好的选择是抑制信息。 – Filburt 2011-01-20 12:34:50

StyleCop SA1600规则和接口实现

回答

相关问题