Documentación de interfaces y su implementación

Question

Estoy decorando mi código C# con comentarios para poder producir archivos de ayuda HTML.

A menudo declaro y documento las interfaces. Pero las clases que implementan esas interfaces pueden arrojar excepciones específicas dependiendo de la implementación.

A veces, el cliente solo conoce las interfaces que está utilizando. ¿Debería documentar mis interfaces agregando las posibles excepciones que podrían arrojar sus implementadores?

¿Debo crear/documentar excepciones personalizadas para que los implementadores de interfaces las publiquen en lugar de las del framework?

¡Espero que esto esté claro!

Gracias

EDITAR 4 º Jan 2010: he decidido escribir un post sobre esto y excepciones personalizadas en .NET en http://blog.mikecouturier.com/2010/01/creating-custom-exceptions-in-net-right.html

Answer 1

No estoy seguro de haber entendido plenamente su pregunta (y yo soy un Java, no desarrollador de C#), pero parece que estás preguntando sobre qué es esencialmente un problema de polimorfismo: si alguien usa un método en una interfaz que se declara para lanzar X e Y, ¿qué ocurre si una implementación arroja Z?

Una cosa a seguir es el principio de conformidad, que esencialmente dice que un subtipo debe ajustarse al comportamiento del supertipo. Es decir, si está documentando que su método en la interfaz solo puede arrojar excepciones de un tipo (por ejemplo, excepciones de puntero nulo), entonces su contrato con los llamantes es que esto es lo único que deben vigilar. Si arrojas algo más, podrías sorprenderlos.

Documentar cosas sobre un subtipo específico en el supertipo no es una buena idea ya que crea un acoplamiento innecesario. Me preocuparía más el hecho de que una implementación pueda comportarse de manera diferente a la declaración, ya que podría sugerir que la declaración no está desarrollada lo suficiente.

Trate de pensar cuáles son todos los tipos de excepciones que su método podría arrojar. Cree supertipos para ellos y luego explícitamente declare en su método de interfaz (por ejemplo, este método puede arrojar alguna "excepción de cálculo"). Luego, en su implementación, genere una excepción de cálculo con más detalles o arroje algún subtipo de la excepción de cálculo que sea específico de la implementación, aún así se conformaría.

Answer 2

Estoy de acuerdo con todo lo que dice Uri: en caso de que sea razonable crear excepciones personalizadas que se pueden extender si es necesario, un método que use un parámetro escrito en su interfaz puede detectar esa excepción y también detectará excepciones subtipadas.

No cree que innecesariamente sin embargo, si hay una excepción .Net Framework existente que describe su condición de error de usar que

En cuanto a la documentación de los implementadores que puede utilizar el apartado de observaciones de los comentarios (asumiendo que' volver a usar comentarios XML) para describir cosas como cómo esperaría que los implementadores hicieran cosas. Obviamente, esto no es de ninguna manera aplicable, pero puede servir como pautas útiles cuando un desarrollador utiliza su API