Dokumentieren Schnittstellen und deren Umsetzung [geschlossen]

Question

Ich bin Dekorieren meiner C # -Code mit Kommentaren, so kann ich HTML-Hilfe-Dateien erzeugen.

ich oft erklären und dokumentieren Schnittstellen. Aber Klassen diese Schnittstellen implementieren, können bestimmte Ausnahmen werfen je nach Implementierung.

Manchmal ist der Kunde nur Kenntnis von den Schnittstellen er benutzt. Soll ich meine Schnittstellen dokumentieren, indem die möglichen Ausnahmen hinzufügen, die durch seine Implementierer geworfen werden könnte?

Sollte ich / Dokument benutzerdefinierte Ausnahmen, so dass Schnittstellen Implementierer diese anstelle von denen des Rahmens werfen?

Ich hoffe, das ist klar!

Danke

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

Answer 1

Ich bin nicht sicher, ob ich voll und ganz Ihre Frage verstanden (und ich bin ein Java, nicht C # -Entwickler), aber es scheint, Sie fragt sich, was ist im Wesentlichen eine Frage des Polymorphismus: Wenn jemand eine Methode einer Schnittstelle verwendet, das ist erklärt zu werfen X und Y, welche Implementierung geschieht, wenn eine Z wirft?

Eine Sache zu folgen ist das Prinzip der Konformität, das im Wesentlichen besagt, dass ein Subtyp auf das Verhalten des Supertypen entsprechen sollte. Das heißt, wenn Sie dokumentieren, dass Ihre Methode in der Schnittstelle nur Ausnahmen von einem Typ werfen kann (beispielsweise Null-Zeiger-Ausnahmen), dann mit Anrufern Ihrem Vertrag ist, dass dies die einzige Sache ist, sollten sie achten Sie auf. Wenn Sie etwas anderes werfen, könnten Sie überraschen sie sein.

Dokumentieren Dinge über einen bestimmten Subtyp in dem Supertyp nicht eine gute Idee, da es unnötig Kopplung erzeugt. Ich wäre mehr besorgt über die Tatsache, dass eine Implementierung anders als die Erklärung verhalten, da das könnte die Erklärung vorschlägt nicht genug konkretisiert.

Man denke nur daran, was sind alle Arten von Ausnahmen, die Ihre Methode werfen könnte. Erstellen Sie übergeordnete Typen für sie, und dann explizit in Ihrer Interface-Methode deklariert (zum Beispiel dieses Verfahren kann einige „Berechnung Ausnahme“ werfen). Dann in Ihrer Implementierung, eine Berechnung Ausnahme mit mehr Details werfen, oder einige Subtyp der Berechnung Ausnahme auslösen, die zur Umsetzung spezifisch ist, würden Sie noch entsprechen.

Answer 2

ich mit allem, was Uri zustimmen sagt - sollten Sie, wo sinnvoll, benutzerdefinierte Ausnahmen erstellen, wenn ein Verfahren erforderlich, erweitert werden kann, dann, die einen Parameter zu Ihrer Schnittstelle eingegeben verwendet, kann diese Ausnahme fangen und es wird Ausnahmen auch fangen subtyped

Sie sie nicht unnötig obwohl schaffen, wenn es eine bestehende .Net Framework Ausnahme, die Bedingung Ihre Fehler beschreibt die Verwendung, die

Im Hinblick auf die für Implementierer dokumentieren Sie den Bemerkungen Abschnitt der Kommentare verwenden können (vorausgesetzt, Sie verwenden XML-Kommentare) Dinge zu beschreiben, wie, wie Sie Implementierer Dinge zu tun erwarten würde. Offensichtlich ist dies in keiner Weise durchsetzbar, aber es kann als nützliche Richtlinien dienen, wenn ein Entwickler kommt Ihre API zu verwenden,