Документирование исключений

Question

У меня есть следующий открытый интерфейс

public interface Bar{
   public void DoStuff();
}

с внутренним внутренним классом

internal class BarImpl : Bar{
   public void DoStuff(){
     // throw exception if invalid state
     // do something
   }
}

Вопрос:

• Только BarImpl реализуетBar интерфейс.
• BarImpl может генерировать исключения в методе DoStuff.

Имеет ли смысл документировать эти исключения в Bar.DoStuff xml doc?

Заранее спасибо,

Answer 1

Да - это было бы так, даже если BarImpl не единственный разработчик.

Пример, который мне нравится использовать, - это класс Stream , в котором абстрактный В методе Read приводится список всех исключений, которые пользователи экземпляра Stream могут ожидать при использовании этого метода, и, в свою очередь, разработчики этого класса должны выдавать их в различных сценариях.

Answer 2

Я документирую только исключения, которые могут быть обработаны. Не имеет смысла документировать любые другие исключения. Мое определение «обработки» исключений состоит в том, что метод может доставить обещанный результат путем перехвата исключения.

Так что этот ответ только для тех исключений:

Если вы хотите следовать принципу открытия / закрытия, вам следует документировать исключения для интерфейса, а не для конкретного класса. И все реализации должны выдавать одно и то же исключение, когда происходит один и тот же сценарий.

Answer 3

Да, это так. Это помогает другим разработчикам быть готовыми и обрабатывать любые исключения, которые могут произойти. Подумайте, сколько раз это помогло вам подготовиться к исключениям, изучив документацию MSDN.