Dokumentation von Interfaces und deren Implementierung

Question

Ich dekoriere meinen C# -Code mit Kommentaren, damit ich HTML-Hilfedateien erzeugen kann.

Ich deklariere und dokumentiere oft Schnittstellen. Aber Klassen, die diese Schnittstellen implementieren, können abhängig von der Implementierung bestimmte Ausnahmen auslösen.

Manchmal weiß der Client nur die Schnittstellen, die er verwendet. Sollte ich meine Schnittstellen dokumentieren, indem ich die möglichen Ausnahmen hinzufüge, die von ihren Implementierern ausgelöst werden könnten?

Sollte ich benutzerdefinierte Ausnahmen erstellen/dokumentieren, so dass Schnittstellenimplementierungen diese anstelle von denen des Frameworks werfen?

Ich hoffe, das ist klar!

Dank

EDIT 4. Januar 2010: Ich beschloss, einen Blog-Post über diese und benutzerdefinierte Ausnahmen in .NET auf http://blog.mikecouturier.com/2010/01/creating-custom-exceptions-in-net-right.html

Answer 1

Ich bin nicht sicher, zu schreiben ich Ihre Frage verstanden hat (und ich bin ein Java, nicht C# -Entwickler), aber es scheint, dass Sie nach etwas fragen, was im Wesentlichen ein Problem des Polymorphismus ist: Wenn jemand eine Methode an einer Schnittstelle benutzt, die X und Y deklariert, was passiert, wenn eine Implementierung Z wirft?

Eine Sache zu folgen ist das Prinzip der Übereinstimmung, die im Wesentlichen besagt, dass ein Subtyp dem Verhalten des Supertyps entsprechen sollte. Das heißt, wenn Sie dokumentieren, dass Ihre Methode in der Schnittstelle nur Ausnahmen eines Typs auslösen kann (z. B. Nullzeigerausnahmen), dann besteht Ihr Vertrag mit Anrufern darin, dass dies die einzige Sache ist, auf die sie achten sollten. Wenn Sie etwas anderes werfen, könnten Sie sie überraschen.

Dokumentieren Sie Dinge über einen bestimmten Subtyp im Supertyp nicht eine gute Idee, da es unnötige Kopplung schafft. Ich wäre eher besorgt darüber, dass sich eine Implementierung anders als die Deklaration verhalten könnte, da dies bedeuten könnte, dass die Deklaration nicht ausreichend ausgearbeitet ist.

Versuchen Sie zu überlegen, welche Arten von Ausnahmen Ihre Methode auslösen könnte. Erstellen Sie übergeordnete Typen für sie, und deklarieren Sie dann explizit in Ihrer Schnittstellenmethode (z. B. kann diese Methode eine "Berechnungsausnahme" auslösen). Werfen Sie in Ihrer Implementierung dann eine Berechnungsausnahme mit mehr Details auf, oder werfen Sie einen Untertyp der Berechnungsausnahme, die für die Implementierung spezifisch ist, nach wie vor konform.

Answer 2

Ich stimme mit allem überein, was Uri sagt - Sie sollten benutzerdefinierte Ausnahmen erstellen, die bei Bedarf erweitert werden können. Eine Methode, die einen an Ihre Schnittstelle eingegebenen Parameter verwendet, kann diese Ausnahme abfangen und auch untergeordnete Ausnahmen abfangen.

Erstellen ihnen nicht unnötig aber, wenn eine bestehende .Net Framework Ausnahme ist, dass Ihr Fehlerzustand Verwendung beschreibt, dass

In Bezug für Implementierer dokumentieren Sie die Bemerkungen Abschnitt der Kommentare verwenden können (vorausgesetzt, Sie‘ Verwenden Sie XML-Kommentare, um Dinge zu beschreiben, die Sie von Implementierern erwarten. Offensichtlich ist dies in keiner Weise durchsetzbar, aber es kann als nützliche Richtlinien dienen, wenn ein Entwickler kommt, Ihre API zu verwenden