Documentar excepciones
-
27-10-2019 - |
Pregunta
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 elBar
interfaz. BarImpl
puede arrojar excepciones en elDoStuff
método.
¿Tiene sentido documentar estas excepciones en el Bar.DoStuff
XML doc?
Gracias por adelantado,
Solución
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.
Otros consejos
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.
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.