Comment documenter les exceptions lancées dans c# / .net [fermé]

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 valeur en faisant cela de cette façon est que vous fournissez la 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 que vous pouvez attendre.

vous voulez spécifier les types d'exception spécifiques, parce que vous pouvez être capable 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.

vous pouvez faciliter votre processus de documentation en utilisant plusieurs grands add-ins. L'un d'eux est GhostDoc , un add-in Gratuit pour Visual Studio qui génère des commentaires XML-doc. Aussi , si vous utilisez ReSharper , jetez un oeil à l'excellent Agent Johnson Plugin pour ReSharper, qui ajoute une option pour générer des commentaires XML pour les exceptions lancées.

mise à jour: il semble que Agen Johnson n'est pas disponible pour R# 8, caisse exceptionnel pour ReSharper comme alternative...

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

étape 1 http://i44.tinypic.com/bdwsk0.png

Étape 2: Utiliser Le raccourci de ReSharper (Alt-Enter) pour ajouter l'exception documentation:

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

Espère que cela aide :)

d'après ce que j'ai compris, l'intention d'utiliser l'élément est de l'utiliser pour décorer des méthodes, et non 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 lancées par d'autres méthodes qui sont appelées devraient être capturées, manipulées et documentées dans ces méthodes. Les Exceptions qui pourraient être lancées par .NET, ou les exceptions qui sont explicitement lancées par votre propre code devraient être documentées.

pour autant que en devenant plus spécifique que cela, peut-être Pouvez-vous attraper et jeter vos propres exceptions personnalisées?

une partie du contrat pour votre méthode devrait être de vérifier que les conditions préalables sont valables, 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 aussi qu'un OutOfMemoryException pourrait être lancé, etc.

vous devez documenter toutes les exceptions qui pourraient éventuellement être lancées par votre méthode.

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

vous pourriez envisager de les retransformer, si vous ne pouvez pas gérer ou résoudre l'exception. La plupart du temps emballé/enveloppé dans une exception plus significative pour l'appelant.

en effet, comme il a déjà été répondu, la façon de documenter les exceptions est D'utiliser des commentaires XML.

en plus des plugins, vous pouvez également utiliser des outils d'analyse statique qui peuvent être intégrés avec TFS pour être sûr que vous avez les exceptions documentées.

Dans les liens ci-dessous vous pouvez voir comment créer une règle personnalisée pour StyleCop pour 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.aspx http://www.josefcobonnin.com/post/2009/01/15/Xml-Documentation-Comments-Exceptions-II.aspx

Cordialement.

Document prévu des exceptions dans votre méthode, dans votre exemple, je voudrais laisser l'utilisateur de savoir que cette méthode permet de lancer un fichier non trouvé exception.

rappelez-vous que c'est pour informer l'appelant de ce qu'il doit attendre afin qu'ils puissent choisir la façon de traiter avec elle.