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

Question

Je suis en train d'écrire un petit cadre 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 la façon de documenter les exceptions lancé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 la documentation des exceptions est:

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

Ce que je ne comprends pas, c'est la façon de documenter les exceptions levées par le code appelé par MyMethod1()?

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

Quelle serait la meilleure façon de documenter d'éventuelles exceptions?

Answer 1

Vous devriez document que chaque exception peut être levée par le code, y compris ceux de toutes les méthodes que vous pourriez appeler.

Si la liste devient un peu plus grand, vous pourriez créer votre propre type d'exception. Attraper tous ceux que vous pourriez rencontrer dans votre méthode, emballez-le dans votre exception, et de les jeter.

Un autre endroit que vous pourriez vouloir faire cela de cette façon, c'est si votre méthode est sur le visage de votre API. Tout comme une façade simplifie interfaces multiples en une seule interface, votre API devrait simplifier les multiples exceptions en une seule exception. Rend l'utilisation de votre code plus facile pour les appelants.

---

Pour répondre à certaines de Andrew préoccupations (de commentaires), il y a trois types d'exceptions: Ceux qui ne le connaissent pas, ceux qui vous connaissent et qui n'y peut rien, et ceux qui vous connaissent et qui peuvent faire quelque chose.

Ceux que vous ne connaissez pas, vous voulez laisser aller. Ses la principale de l'échec rapide--mieux à votre application d'accident que dans un état où vous risquez de corrompre vos données. Le plantage de vous parler de ce qui s'est passé et pourquoi, ce qui peut aider à déplacer l'exception de ceux que vous ne connaissez pas" à la liste.

Ceux qui vous connaissent et qui ne peut rien faire sur sont des exceptions comme le OutOfMemoryExceptions. Dans les cas extrêmes, vous pourriez gérer les exceptions de ce genre, mais à moins d'avoir une assez remarquable exigences de vous traiter comme le premier de la catégorie--let 'em aller. - Vous avez de la documentation de ces exceptions? Vous auriez l'air assez stupide documenter OOMs sur chaque méthode unique que les nouveaux-s d'un objet.

Ceux que vous connaissez et qu'il peut faire quelque chose sont ceux que vous devriez être de la documentation et de l'emballage.

Vous pouvez trouver des lignes directrices sur la manipulation d'exception ici.

Answer 2

Vous devez utiliser la norme xml de la documentation.

/// <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 valeur en le faisant de cette manière, c'est que vous êtes fournissant de la documentation de l'connu des exceptions qui peuvent se produire. Cette documentation est disponible dans le intellisense si vous utilisez visual studio et peut vous rappeler (ou d'autres), plus tard, des exceptions que vous pouvez vous attendre.

Vous souhaitez spécifier l'exception spécifique types, parce que vous pourriez être en mesure de gérer un type d'exception, alors que d'autres sont le résultat d'un problème grave qui ne peut être corrigée.

Answer 3

Vous pouvez rendre vos documents plus facilement à l'aide de plusieurs grands add-ins. L'un d'eux est GhostDoc, gratuit add-in pour Visual Studio qui génère le XML doc commentaires. Aussi, si vous utilisez ReSharper, jetez un oeil à l'excellent Agent Johnson Plugin pour ReSharper, ce qui ajoute une option pour générer des commentaires XML pour les exceptions lancées:

Étape 1: GhostDoc génère le XML commentaire (Ctrl-Maj-D), tandis que l'Agent Johnson plugin pour ReSharper suggère de documenter le exception:

Étape 2: Utilisation de ReSharper la touche de raccourci (Alt-Enter) pour ajouter l'exception la documentation ainsi:

Espérons que cela aide :)

Answer 4

Ce que je comprends, l'intention d'utiliser la <exception> élément est à utiliser lors de la décoration de méthodes, pas d'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 qui sont appelés doivent être pris, traités et documentés dans ces méthodes. Les Exceptions qui pourraient éventuellement jetés par .NET, ou des exceptions qui sont explicitement jetés par votre propre code doit être documentée.

Quant à trouver plus précis que ça, peut-être que vous pouvez attraper et lancer vos propres exceptions?

Answer 5

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

 /// <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 OutOfMemoryException peut être généré, etc.