Реализация правила и интерфейсов StyleCop SA1600

Правило StyleCop SA1600 требует, чтобы каждый член типа имел собственный заголовок документации. Думаю, это вполне разумно, и мне нравится это правило. Но предположим, что у нас есть следующая иерархия:

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

    /// 
    /// Documentation for DoB.
    /// 
    void DoB();
}

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

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

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

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

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

Здесь я полностью задокументировал члены интерфейса DoA () и DoB (), мы знаем, что именно делают эти методы, из документации интерфейса. VS Intellisence тоже это знает, и мы можем увидеть описание методов, наведя указатель мыши на эти методы даже в классе StandardModule. Таким образом, нет необходимости копировать документацию из интерфейса в производный класс. Но StyleCop требует этого. Почему? Кто-нибудь знает?

Если мы попытаемся решить эту проблему, мы можем пойти 4 разными способами:

1. Скопируйте документацию из интерфейса. Проблема здесь в том, что если мы скопируем документацию, мы столкнемся с проблемой обновления документации во всех производных классах, если поведение интерфейса изменится.

2. Подавить сообщение с помощью SuppressMessageAttribute . Что ж, предположим, мы говорим: «Хорошо, я могу использовать SuppressMessageAttribute», чтобы подавить это нарушение, с которым я не согласен. И я добавляю класс StandardModule с атрибутом SuppressMessageAttribute для правила SA1600. Но теперь StyleCop вообще перестает проверять заголовки документации в классе StandardModule. Я не хочу этого, потому что у нас есть конструктор и еще несколько методов

3. Разделить класс на регионы, Мы можем разделить класс StandardModule на 2 области и использовать подавление сообщений только на той части, которая реализует интерфейс ISomeModule. И я считаю, что все части должны быть помещены в один файл. Мне больше всего нравится этот подход (после способа №4), но теперь нам приходится иметь дело с несколькими частями одного класса.

4. Измените правило SA1600. Можно ли сделать мою собственную реализацию правила SA1600, чтобы она учитывала, были ли члены класса задокументированы в базовом классе или в интерфейсе? (здесь я не спрашиваю, можем ли мы написать собственное правило для StyleCop, я знаю, что можем, но я имею в виду, может ли движок StyleCop проверять, пришли ли некоторые члены из интерфейса или из базового класса).

Какой способ является наиболее предпочтительным. решить проблему SA1600 по реализации интерфейса?

14
задан Dmitrii Lobanov 20 January 2011 в 11:17
поделиться