So dokumentieren Sie ausgelöste Ausnahmen in c # /. Net

Ich schreibe derzeit ein kleines Framework, das intern von anderen Entwicklern im Unternehmen verwendet wird.

Ich möchte gute Intellisense-Informationen bereitstellen, bin mir jedoch nicht sicher, wie ausgelöste Ausnahmen dokumentiert werden sollen.

Im folgenden Beispiel:

public void MyMethod1()
{
    MyMethod2();

    // also may throw InvalidOperationException
}

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

    // also may throw DivideByZeroException
}

Ich weiß, dass das Markup für die Dokumentation von Ausnahmen lautet:

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

Was ich nicht verstehe, ist, wie Ausnahmen dokumentiert werden, die durch den von aufgerufenen Code ausgelöst werdenMyMethod1() ?

• Soll ich Ausnahmen dokumentieren, die von ausgelöst werden? MyMethod2()
• Soll ich Ausnahmen dokumentieren, die von ausgelöst werden File.Open()?

Was wäre der beste Weg, um mögliche Ausnahmen zu dokumentieren?

Sie sollten jede Ausnahme dokumentieren, die von Ihrem Code ausgelöst wird, einschließlich derjenigen in Methoden, die Sie möglicherweise aufrufen.

Wenn die Liste etwas größer wird, möchten Sie möglicherweise Ihren eigenen Ausnahmetyp erstellen. Fangen Sie alle auf, auf die Sie in Ihrer Methode stoßen könnten, schließen Sie sie in Ihre Ausnahme ein und werfen Sie sie aus.

Ein anderer Ort, an dem Sie dies möglicherweise tun möchten, ist, wenn sich Ihre Methode auf der Vorderseite Ihrer API befindet. So wie eine Fassade mehrere Schnittstellen zu einer einzigen Schnittstelle vereinfacht, sollte Ihre API mehrere Ausnahmen zu einer einzigen Ausnahme vereinfachen. Erleichtert Anrufern die Verwendung Ihres Codes.

Um einige von Andrews Bedenken zu beantworten (aus den Kommentaren), gibt es drei Arten von Ausnahmen: Eine, von der Sie nichts wissen, die Sie kennen und gegen die Sie nichts tun können, und die, die Sie kennen und gegen die Sie etwas tun können.

Diejenigen, von denen Sie nichts wissen, wollen Sie loslassen. Es ist das Prinzip, schnell zu versagen - es ist besser, wenn Ihre App abstürzt, als in einen Zustand zu gelangen, in dem Sie möglicherweise Ihre Daten beschädigen. Der Absturz informiert Sie darüber, was passiert ist und warum. Dies kann dazu beitragen, diese Ausnahme aus der Liste "Diejenigen, von denen Sie nichts wissen" zu entfernen.

Diejenigen, die Sie kennen und gegen die Sie nichts tun können, sind Ausnahmen wie OutOfMemoryExceptions. In extremen Fällen möchten Sie vielleicht Ausnahmen wie diese behandeln, aber wenn Sie keine bemerkenswerten Anforderungen haben, behandeln Sie sie wie die erste Kategorie - lassen Sie sie los. Haben Sie haben auf diese Ausnahmen zu dokumentieren? Sie würden ziemlich dumm aussehen, OOMs für jede einzelne Methode zu dokumentieren, mit der ein Objekt neu erstellt wird.

Diejenigen, die Sie kennen und gegen die Sie etwas tun können, sollten Sie dokumentieren und verpacken.

Weitere Richtlinien zur Ausnahmebehandlung finden Sie hier.

Sie sollten die Standard-XML-Dokumentation verwenden .

/// <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.");
    }
}

Der Wert auf diese Weise besteht darin, dass Sie die bekannten Ausnahmen dokumentieren, die auftreten können. Diese Dokumentation ist in Intellisense verfügbar, wenn Sie Visual Studio verwenden, und kann Sie (oder andere) später an die Ausnahmen erinnern, die Sie erwarten können.

Sie möchten die spezifischen Ausnahmetypen angeben, da Sie möglicherweise einen Ausnahmetyp behandeln können, während andere Typen das Ergebnis eines schwerwiegenden Problems sind und nicht korrigiert werden können.

Sie können Ihren Dokumentationsprozess vereinfachen, indem Sie mehrere großartige Add-Ins verwenden. Eines davon ist GhostDoc , ein kostenloses Add-In für Visual Studio, das XML-Doc-Kommentare generiert. Wenn Sie ReSharper verwenden , sehen Sie sich auch das hervorragende Agent Johnson Plugin für ReSharper an, das eine Option zum Generieren von XML-Kommentaren für ausgelöste Ausnahmen hinzufügt.

Update: Es scheint, dass Agen Johnson für R # 8 nicht verfügbar ist. Checkout Außergewöhnlich für ReSharper als Alternative ...

Schritt 1: GhostDoc generiert den XML-Kommentar (Strg-Umschalt-D), während das Agent Johnson-Plugin für ReSharper vorschlägt, die Ausnahme ebenfalls zu dokumentieren:

Schritt 2: Verwenden Sie die Tastenkombination von ReSharper (Alt-Enter), um auch die Ausnahmedokumentation hinzuzufügen:

Schritt 2 http://i41.tinypic.com/osdhm

Hoffentlich hilft das :)

Soweit ich weiß, besteht die Absicht der Verwendung des <exception> -Elements darin, es beim Dekorieren von Methoden zu verwenden, nicht von Ausnahmen:

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

Ausnahmen, die von anderen aufgerufenen Methoden ausgelöst werden können, sollten in diesen Methoden abgefangen, behandelt und dokumentiert werden. Ausnahmen, die möglicherweise von .NET ausgelöst werden könnten, oder Ausnahmen, die explizit von Ihrem eigenen Code ausgelöst werden, sollten dokumentiert werden.

Wenn Sie genauer sind, können Sie vielleicht Ihre eigenen benutzerdefinierten Ausnahmen abfangen und auslösen?

Teil des Vertrags für Ihre Methode sollte sein, zu überprüfen, ob die Voraussetzungen gültig sind, also:

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

wird

/// <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
}

Mit diesem Ansatz ist es einfacher, alle Ausnahmen zu dokumentieren, die Sie explizit auslösen, ohne auch dokumentieren zu müssen, dass a OutOfMemoryException möglicherweise ausgelöst wird usw.

Sie sollten alle Ausnahmen dokumentieren, die möglicherweise von Ihrer Methode ausgelöst werden könnten.

Um die Implementierungsdetails auszublenden, würde ich versuchen, einige Ausnahmen von MyMethod2 selbst zu behandeln.

Sie könnten in Betracht ziehen, sie erneut zu speichern, wenn Sie die Ausnahme nicht behandeln oder lösen können. Meistens verpackt / verpackt in einer aussagekräftigeren Ausnahme für den Anrufer.

Wie bereits beantwortet, werden XML-Kommentare zur Dokumentation der Ausnahmen verwendet.

Zusätzlich zu den Plugins können Sie auch statische Analysetools verwenden, die in TFS integriert werden können, um sicherzustellen, dass die Ausnahmen dokumentiert sind.

Unter den folgenden Links können Sie sehen, wie Sie eine benutzerdefinierte Regel für StyleCop erstellen, um zu überprüfen, ob die von Ihren Methoden ausgelösten Ausnahmen dokumentiert werden.

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

Grüße.

Dokumentieren Sie erwartete Ausnahmen in Ihrer Methode. In Ihrem Beispiel würde ich den Benutzer wissen lassen, dass diese Methode eine Datei auslösen kann, bei der keine Ausnahme gefunden wurde.

Denken Sie daran, dass Sie den Anrufer darüber informieren müssen, was ihn erwartet, damit er entscheiden kann, wie er damit umgehen soll.