Comment documenter les exceptions levées dans c # /. Net

J’écris actuellement un petit framework qui sera utilisé en interne par d’autres développeurs au sein de l’entreprise.

Je veux fournir de bonnes informations Intellisense, mais je ne suis pas sûr de savoir comment documenter les exceptions levées.

Dans l’exemple suivant:

public void MyMethod1() { MyMethod2(); // also may throw InvalidOperationException } public void MyMethod2() { System.IO.File.Open(somepath...); // this may throw FileNotFoundException // also may throw DivideByZeroException } 

Je sais que le balisage pour documenter les exceptions est:

 /// when things go wrong. 

Ce que je ne comprends pas, c’est comment documenter les exceptions lancées par le code appelé par MyMethod1() ?

  • Dois-je documenter les exceptions lancées par MyMethod2()
  • Dois-je documenter les exceptions lancées par File.Open() ?

Quelle serait la meilleure façon de documenter les exceptions possibles?

Vous devez documenter toutes les exceptions pouvant être émises par votre code, y compris celles de toutes les méthodes que vous pourriez appeler.

Si la liste est un peu volumineuse, vous pouvez créer votre propre type d’exception. Catch tous ceux que vous pourriez rencontrer dans votre méthode, les envelopper dans votre exception, et lancez cela.

Un autre endroit où vous voudrez peut-être le faire est si votre méthode est à la face de votre API. Tout comme une façade simplifie plusieurs interfaces dans une seule interface, votre API doit simplifier plusieurs exceptions en une seule exception. Facilite l’utilisation de votre code pour les appelants.


Pour répondre à certaines des préoccupations d’Andrew (à partir des commentaires), il existe trois types d’exceptions: ceux que vous ne connaissez pas, ceux que vous connaissez et auxquels vous ne pouvez rien faire, et ceux que vous connaissez et auxquels vous pouvez faire quelque chose.

Ceux que vous ne connaissez pas veulent vous laisser aller. C’est le principe de la défaillance rapide – mieux vaut planter votre application que d’entrer dans un état où vous pourriez finir par corrompre vos données. Le crash vous dira ce qui s’est passé et pourquoi, ce qui peut aider à sortir cette exception de la liste “ceux que vous ne connaissez pas”.

Ceux que vous connaissez et auxquels vous ne pouvez rien faire sont des exceptions comme OutOfMemoryExceptions. Dans les cas extrêmes, vous pouvez gérer des exceptions comme celle-ci, mais à moins que vous ayez des exigences assez remarquables, vous les traitez comme la première catégorie – allons-y. Devez-vous documenter ces exceptions? Vous auriez l’air assez idiot de documenter les MOO sur chaque méthode qui crée un object.

Ceux que vous connaissez et que vous pouvez utiliser sont ceux que vous devez documenter et emballer.

Vous pouvez trouver plus de directives sur la gestion des exceptions ici.

Vous devez utiliser la documentation xml standard .

 /// Why it's thrown. /// Why it's thrown. /// Why it's thrown. public void MyMethod1() { MyMethod2(); // ... other stuff here } /// Why it's thrown. /// Why it's thrown. public void MyMethod2() { System.IO.File.Open(somepath...); } /// Why it's thrown. public void MyMethod3() { try { MyMethod2(); } catch (DivideByZeroException ex) { Trace.Warning("We sortinged to divide by zero, but we can continue."); } } 

Le fait de le faire de cette manière est que vous fournissez la documentation des exceptions connues qui peuvent se produire. Cette documentation est disponible dans IntelliSense si vous utilisez Visual Studio et peut vous rappeler (ou d’autres) plus tard les exceptions auxquelles vous pouvez vous attendre.

Vous souhaitez spécifier les types d’exception spécifiques, car vous pouvez gérer un type d’exception, alors que d’autres types résultent d’un problème grave et ne peuvent pas être corrigés.

Vous pouvez faciliter votre processus de documentation en utilisant plusieurs add-ins géniaux. L’un d’eux est GhostDoc , un complément gratuit pour Visual Studio qui génère des commentaires XML-doc. De plus, si vous utilisez ReSharper , consultez l’excellent plugin Agent Johnson pour ReSharper, qui ajoute une option pour générer des commentaires XML pour les exceptions levées.

Mise à jour: Il semble qu’Agen Johnson ne soit pas disponible pour le R # 8, passez à la caisse Exceptional for ReSharper comme alternative …

Étape 1: GhostDoc génère le commentaire XML (Ctrl-Shift-D), tandis que le plug-in Agent Johnson pour ReSharper suggère également de documenter l’exception:

étape 1 http://soffr.miximages.com/c%23/bdwsk0.png

Étape 2: Utilisez la touche de raccourci de ReSharper (Alt-Entrée) pour append également la documentation relative à l’exception:

étape 2 http://i41.tinypic.com/osdhm

J’espère que cela pourra aider 🙂

D’après ce que j’ai compris, l’intention d’utiliser l’élément est de l’utiliser lors de la décoration de méthodes, et non d’exceptions:

 /// Does something! /// Thrown if nothing is actually done. public void DoSomething() { // There be logic here } 

Les exceptions pouvant être lancées par d’autres méthodes appelées doivent être détectées, traitées et documentées dans ces méthodes. Les exceptions susceptibles d’être lancées par .NET ou les exceptions explicitement lancées par votre propre code doivent être documentées.

En ce qui concerne les détails, vous pouvez peut-être attraper et lancer vos propres exceptions personnalisées?

Une partie du contrat pour votre méthode devrait être de vérifier que les conditions préalables sont valides, donc:

 public void MyMethod2() { System.IO.File.Open(somepath...); // this may throw FileNotFoundException } 

devient

 /// Thrown when somepath isn't a real file. public void MyMethod2() { FileInfo fi = new FileInfo( somepath ); if( !fi.Exists ) { throw new FileNotFoundException("somepath doesn't exists") } // Maybe go on to check you have permissions to read from it. System.IO.File.Open(somepath...); // this may still throw FileNotFoundException though } 

Avec cette approche, il est plus facile de documenter toutes les exceptions que vous lancez explicitement sans avoir à documenter qu’une OutOfMemoryException peut être levée, etc.

Vous devez documenter toutes les exceptions qui pourraient être provoquées par votre méthode.

Pour masquer les détails de l’implémentation, j’essaierais de gérer certaines exceptions de MyMethod2 moi-même.

Vous pouvez envisager de les rentrer, si vous ne pouvez pas gérer ou résoudre l’exception. Principalement empaqueté / emballé dans une exception plus significative pour l’appelant.

En effet, comme il a déjà été répondu, la manière de documenter les exceptions utilise les commentaires XML.

En plus des plug-ins, vous pouvez également utiliser des outils d’parsing statique pouvant être intégrés à TFS pour vous assurer que les exceptions sont documentées.

Dans les liens ci-dessous, vous pouvez voir comment créer une règle personnalisée pour que StyleCop valide les exceptions lancées par vos méthodes.

http://www.josefcobonnin.com/post/2009/01/11/Xml-Documentation-Comments-Exceptions-I.aspx http://www.josefcobonnin.com/post/2009/01/15/Xml-Documentation -Commentaires-Exceptions-II.aspx

Cordialement.

Documenter les exceptions attendues dans votre méthode, dans votre exemple, je voudrais que l’utilisateur sache que cette méthode peut générer une exception de fichier introuvable.

Rappelez-vous que c’est pour informer l’appelant de ce à quoi ils peuvent s’attendre afin qu’ils puissent choisir comment y faire face.