Documentation des interfaces et de leur implémentation [fermé]

Question

Je décore mon code C # avec des commentaires pour pouvoir générer des fichiers d'aide HTML.

Je déclare et documente souvent des interfaces. Toutefois, les classes implémentant ces interfaces peuvent générer des exceptions spécifiques en fonction de la mise en œuvre.

Parfois, le client est seulement conscient des interfaces qu'il utilise. Dois-je documenter mes interfaces en ajoutant les exceptions possibles que pourraient avoir ses implémenteurs?

Devrais-je créer / documenter des exceptions personnalisées afin que les implémenteurs d'interfaces les envoient à la place de celles du framework?

J'espère que c'est clair!

Merci

EDIT le 4 janvier 2010: j’ai décidé de rédiger un blog sur cette exception et les exceptions personnalisées dans .NET à http://blog.mikecouturier.com/2010/01/creating-custom-exceptions-in-net-right.html

Answer 1

Je ne suis pas sûr d'avoir parfaitement compris votre question (et je suis un développeur Java, pas un développeur C #), mais il semble que vous posiez des questions sur ce qui est essentiellement une question de polymorphisme: si quelqu'un utilise une méthode sur une interface déclaré lancer X et Y, que se passe-t-il si une implémentation jette Z?

Une chose à suivre est le principe de conformité, qui dit essentiellement qu'un sous-type doit être conforme au comportement du supertype. En d’autres termes, si vous expliquez que votre méthode dans l’interface ne peut émettre que des exceptions d’un type (par exemple, des exceptions de pointeur nul), votre contrat avec les appelants stipule que c’est la seule chose à surveiller. Si vous jetez quelque chose d'autre, vous pourriez les surprendre.

Documenter des choses sur un sous-type spécifique dans le super-type n’est pas une bonne idée car il crée un couplage inutile. Je serais plus préoccupé par le fait qu'une mise en œuvre puisse se comporter différemment d'une déclaration, car cela pourrait laisser penser que la déclaration n'est pas suffisamment étoffée.

Essayez de penser à tous les types d’exceptions que votre méthode pourrait générer. Créez des supertypes pour eux, puis déclarez explicitement dans votre méthode d'interface (par exemple, cette méthode peut générer des "exceptions de calcul"). Ensuite, dans votre implémentation, émettez une exception de calcul avec plus de détails ou un sous-type de l’exception de calcul spécifique à l’implémentation, vous vous en conformeriez quand même.

Answer 2

Je suis d'accord avec tout ce que dit Uri - vous devriez créer des exceptions personnalisées qui peuvent être étendues si nécessaire, puis une méthode qui utilise un paramètre typé sur votre interface peut intercepter cette exception et également les exceptions sous-typées.

Cependant, ne les créez pas inutilement, s'il existe une exception .Net Framework décrivant votre condition d'erreur, utilisez cette

.

En termes de documentation pour les implémenteurs, vous pouvez utiliser la section remarques des commentaires (en supposant que vous utilisiez des commentaires XML) pour décrire des choses telles que la manière dont vous attendez des implémenteurs. Évidemment, cela n’est nullement exécutoire, mais cela peut servir de guide utile lorsqu'un développeur vient d’utiliser votre API