Documentar excepciones

Question

Tengo la siguiente interfaz pública

public interface Bar{
   public void DoStuff();
}

con una clase interna de back -end

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

La pregunta:

• Solamente BarImpl implementa el Bar interfaz.
• BarImpl puede arrojar excepciones en el DoStuff método.

¿Tiene sentido documentar estas excepciones en el Bar.DoStuff XML doc?

Gracias por adelantado,

Answer 1

Sí, este sería el caso incluso si BarImpl No es el único implementador.

El ejemplo que me gusta usar es el Corriente clase donde el resumen Leer El método enumera una carga completa de excepciones que los usuarios de un Stream La instancia podría esperar que se arroje cuando se use este método, y a su vez los implementadores de esta clase deberían lanzar en varios escenarios.

Answer 2

Si lo hace. Ayuda a otros desarrolladores a estar preparados y a manejar cualquier excepción que pueda ocurrir. Piense en cuántas veces le ayudó a prepararse para las excepciones al pasar por la documentación de MSDN.

Answer 3

Solo documento excepciones que podrían manejarse. No tiene sentido documentar otras excepciones. Mi definición de excepciones de "manejo" es que el método puede entregar el resultado prometido al atrapar la excepción.

Entonces, esta respuesta es solo para esas excepciones:

Si desea seguir el principio abierto/cerrado, debe documentar las excepciones para la interfaz y no para la clase concreta. Y todas las implementaciones deben lanzar la misma excepción cuando ocurre el mismo escenario.