documenter exceptions

Question

Je l'interface publique suivante

public interface Bar{
   public void DoStuff();
}

avec une classe d'extrémité arrière interne

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

La question:

• implémente uniquement de BarImpl l'interface Bar.
• BarImpl peut lancer des exceptions dans la méthode DoStuff.

Est-il judicieux de documenter ces exceptions dans le Bar.DoStuff xml doc?

Merci à l'avance,

Answer 1

Oui -. Ce serait le cas même si BarImpl est pas le seul implementor

L'exemple que je tiens à utiliser est la classe de ruisseau où le listes abstraite méthode Lire d'une charge d'exceptions que les utilisateurs d'une instance de Stream pourraient attendre à être jeté lors de l'utilisation de cette méthode, et tour à tour les implémenteurs de cette classe devrait jeter sous différents scénarios.

Answer 2

Oui, il le fait. Il aide les autres développeurs à préparer et à gérer toute exception qui pourrait se produire. Pensez combien de fois il vous a aidé à vous préparer des exceptions en passant par la documentation MSDN.

Answer 3

Je décrirons ici que des exceptions qui pourraient être traitées. N'a pas de sens pour documenter d'autres exceptions. Ma définition de « manipulation » des exceptions est que la méthode peut fournir le résultat promis en attrapant l'exception.

Donc, cette réponse est que pour les exceptions:

Si vous voulez suivre le principe ouvert / fermé, vous devez documenter les exceptions pour l'interface et non la classe de béton. Et toutes les implémentations doivent lancer la même exception lorsque le même scénario se produit.