web-dev-qa-db-fra.com

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 souhaite fournir de bonnes informations Intellisense, mais je ne sais pas 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:

/// <exception cref="SomeException">when things go wrong.</exception>

Ce que je ne comprends pas, c'est comment documenter les exceptions levées par le code appelé parMyMethod1()?

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

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

c#.netdocumentationintellisense
135
Arnold Zokas

Vous devez documenter toutes les exceptions susceptibles d'être levées par votre code, y compris celles des méthodes que vous pourriez appeler.

Si la liste devient un peu grande, vous souhaiterez peut-être créer votre propre type d'exception. Attrapez tous ceux que vous pourriez rencontrer dans votre méthode, enveloppez-les dans votre exception et lancez-les.

Un autre endroit où vous voudrez peut-être le faire de cette façon est si votre méthode est sur le visage de votre API. Tout comme une façade simplifie plusieurs interfaces en 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 (des commentaires), il existe trois types d'exceptions: celles que vous ne connaissez pas, celles que vous connaissez et auxquelles vous ne pouvez rien faire, et celles que vous connaissez et pouvez faire quelque chose.

Ceux que vous ne connaissez pas veulent vous lâcher. C'est le principe de l'échec rapide - mieux vaut que votre application tombe en panne que d'entrer dans un état où vous pourriez finir par corrompre vos données. Le plantage vous dira ce qui s'est passé et pourquoi, ce qui peut aider à déplacer cette exception de la liste des "personnes 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 voudrez peut-être gérer des exceptions comme celle-ci, mais à moins d'avoir des exigences assez remarquables, vous les traitez comme la première catégorie - laissez-les partir. Avez-vous pour documenter ces exceptions? Vous auriez l'air assez idiot de documenter les MOO sur chaque méthode qui crée un objet.

Ceux que vous connaissez et sur lesquels vous pouvez faire quelque chose sont ceux que vous devriez documenter et emballer.

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

106
Will

Vous devez utiliser la documentation xml standard .

/// <exception cref="InvalidOperationException">Why it's thrown.</exception>
/// <exception cref="FileNotFoundException">Why it's thrown.</exception>
/// <exception cref="DivideByZeroException">Why it's thrown.</exception>
public void MyMethod1()
{
    MyMethod2();
    // ... other stuff here
}

/// <exception cref="FileNotFoundException">Why it's thrown.</exception>
/// <exception cref="DivideByZeroException">Why it's thrown.</exception>
public void MyMethod2()
{
    System.IO.File.Open(somepath...);
}

/// <exception cref="FileNotFoundException">Why it's thrown.</exception>
public void MyMethod3()
{
    try
    {
        MyMethod2();
    }
    catch (DivideByZeroException ex)
    {
        Trace.Warning("We tried to divide by zero, but we can continue.");
    }
}

La façon de procéder de cette manière est que vous fournissez une documentation des exceptions connues qui peuvent se produire. Cette documentation est disponible dans l'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'exceptions spécifiques, car vous pourrez peut-être gérer un type d'exception, tandis que d'autres types sont le résultat d'un problème grave et ne peuvent pas être corrigés.

91
chills42

Vous pouvez faciliter votre processus de documentation en utilisant plusieurs excellents compléments. L'un d'eux est GhostDoc , un complément gratuit pour Visual Studio qui génère des commentaires XML-doc. En outre, si vous utilisez ReSharper , jetez un œil à l'excellent Agent Johnson Plugin 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 R # 8, checkout Exceptionnel pour 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:

step 1

Étape 2: Utilisez également la touche de raccourci de ReSharper (Alt-Entrée) pour ajouter la documentation d'exception:

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

J'espère que ça t'as aidé :)

34
Igal Tabachnik

D'après ce que je comprends, l'intention d'utiliser l'élément <exception> est de l'utiliser pour décorer des méthodes, pas des exceptions:

/// <summary>Does something!</summary>
/// <exception cref="DidNothingException">Thrown if nothing is actually done.</exception>
public void DoSomething()
{
// There be logic here
}

Les exceptions qui peuvent être levées par d'autres méthodes appelées doivent être interceptées, gérées et documentées dans ces méthodes. Les exceptions qui pourraient éventuellement être levées par .NET, ou les exceptions qui sont explicitement levées par votre propre code doivent être documentées.

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

10
Daniel Schaffer

Une partie du contrat de votre méthode doit consister à vérifier que les conditions préalables sont valides, donc:

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

devient

/// <exception cref="FileNotFoundException">Thrown when somepath isn't a real file.</exception>
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 également qu'un OutOfMemoryExceptionpourrait être levé, etc.

4
Rowland Shaw

Vous devez documenter toutes les exceptions susceptibles d'être levées par votre méthode.

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

Vous pouvez envisager de les rétracter si vous ne pouvez pas gérer ou résoudre l'exception. Généralement empaqueté/enveloppé dans une exception plus significative pour l'appelant.

1
GvS

En effet, comme il a déjà été répondu, le moyen de documenter les exceptions est d'utiliser les commentaires XML.

En plus des plugins, vous pouvez également utiliser des outils d'analyse statique qui peuvent ê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 StyleCop afin de valider les exceptions levées par vos méthodes sont documentées.

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

Cordialement.

1
Jose

Documentez les exceptions attendues dans votre méthode, dans votre exemple, je ferais savoir à l'utilisateur que cette méthode peut lever une exception de fichier introuvable.

N'oubliez pas que c'est pour informer l'appelant de ce à quoi il peut s'attendre afin qu'il puisse choisir comment y faire face.

0
Damien