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

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

14 голосов
/ 20 января 2011

Правило 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 с SuppressMessageAttribute для правила SA1600.Но теперь StyleCop вообще перестает проверять заголовки документации в классе StandardModule.Я не хочу этого, потому что у нас есть конструктор и некоторые другие методы.

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

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

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

Ответы [ 2 ]

8 голосов
/ 20 января 2011

Мне никогда не приходило в голову, что это будет проблемой, потому что я всегда рассматривал документацию объявления интерфейса как нечто отличное от документации реализации этого интерфейса .

Я могу ошибаться, но я счастлив учиться.

Мой фактический ответ на ваш вопрос будет следующим: 1) Скопируйте Переведите документацию с интерфейса.

7 голосов
/ 20 января 2011

Предполагается, что в следующем выпуске StyleCop 4.4.1 будет поддерживаться тег наследования. Если вы хотите использовать инструмент создания документации, который поддерживает этот тег (например: Sandcastle или FiXml ), у вас может быть работающее решение, которое решит обе ваши проблемы. 1005 *

...