Документирование исключений
-
27-10-2019 - |
Вопрос
У меня есть следующий общественный интерфейс
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?
Заранее спасибо,
Решение
Да, это было бы так, даже если бы BarImpl
не единственный реализатор.
Пример, который я люблю использовать, - это Ручей класс, где абстрактный Читать Метод перечисляет целую нагрузку исключений, что пользователи Stream
Экземпляр может ожидать, что будет брошен при использовании этого метода, и, в свою очередь, реализации этого класса должны бросать в различных сценариях.
Другие советы
Да, это так. Это помогает другим разработчикам быть подготовленными и справиться с любым исключением, которое может произойти. Подумайте, сколько раз это помогло вам подготовиться к исключениям, пройдя через документацию MSDN.
Я документирую только исключения, которые можно обработать. Не имеет смысла документировать какие -либо другие исключения. Мое определение «обработки» исключений заключается в том, что метод может дать обещанный результат, поймав исключение.
Итак, этот ответ предназначен только для этих исключений:
Если вы хотите следовать принципу открытого/закрытого, вы должны задокументировать исключения для интерфейса, а не бетонного класса. И все реализации должны делать одно и то же исключение, когда происходит один и тот же сценарий.