Правило 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 по реализации интерфейса?