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