Interfaces de documentación y su implementación [cerrado]

Question

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

A menudo declaro y documento 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. ¿Debo documentar mis interfaces agregando las posibles excepciones que podrían lanzar sus implementadores?

¿Debería crear / documentar excepciones personalizadas para que los implementadores de interfaces las arrojen en lugar de las del marco?

¡Espero que esto esté claro!

Gracias

EDIT 4 de enero de 2010: decidí escribir una publicación de blog 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 completamente su pregunta (y soy un desarrollador de Java, no de C #), pero parece que está preguntando qué es esencialmente un problema de polimorfismo: si alguien usa un método en una interfaz que es declaró lanzar X e Y, ¿qué sucede 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 generar excepciones de un tipo (por ejemplo, excepciones de puntero nulo), entonces su contrato con las personas que llaman es que esto es lo único que deben tener en cuenta. 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 puede comportarse de manera diferente a la declaración, ya que eso podría sugerir que la declaración no se ha desarrollado lo suficiente.

Intenta pensar cuáles son todos los tipos de excepciones que tu método podría generar. Cree supertipos para ellos y luego declare explícitamente en su método de interfaz (por ejemplo, este método puede arrojar alguna `` excepción de cálculo ''). Luego, en su implementación, arroje 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ífica de la implementación, aún así se conformaría.

Answer 2

Estoy de acuerdo con todo lo que dice Uri: si es necesario, cree excepciones personalizadas que se puedan extender si es necesario, entonces un método que utiliza un parámetro escrito en su interfaz puede detectar esa excepción y también detectará excepciones subtipadas.

Sin embargo, no los cree innecesariamente, si hay una excepción de .Net Framework que describe su condición de error, use eso

En términos de documentación para implementadores, puede usar la sección de comentarios de los comentarios (suponiendo que esté usando comentarios XML) para describir cosas como cómo esperaría que los implementadores hicieran cosas. Obviamente, esto no es de ninguna manera exigible, pero puede servir como pautas útiles cuando un desarrollador utiliza su API