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

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 Экземпляр может ожидать, что будет брошен при использовании этого метода, и, в свою очередь, реализации этого класса должны бросать в различных сценариях.

Answer 2

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

Answer 3

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

Итак, этот ответ предназначен только для этих исключений:

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