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

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?

Заранее благодарен,

Answer 1

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

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

Answer 2

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

Answer 3

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

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

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