Ausnahmen dokumentieren

Question

Ich habe die folgende öffentliche Schnittstelle

public interface Bar{
   public void DoStuff();
}

mit einer internen Back -End -Klasse

internal class BarImpl : Bar{
   public void DoStuff(){
     // throw exception if invalid state
     // do something
   }
}

Die Frage:

• Nur BarImpl implementiert die Bar Schnittstelle.
• BarImpl kann Ausnahmen in die DoStuff Methode.

Ist es sinnvoll, diese Ausnahmen in der zu dokumentieren? Bar.DoStuff xml doc?

Danke im Voraus,

Answer 1

Ja - das wäre der Fall, auch wenn BarImpl ist nicht der einzige Implementierer.

Das Beispiel, das ich gerne benutze, ist das Strom Klasse, in der die Zusammenfassung Lesen Die Methode listet eine ganze Menge Ausnahmen auf, die Benutzer von a Stream Die Instanz könnte erwarten, dass sie bei der Verwendung dieser Methode geworfen werden, und die Implementierer dieser Klasse sollten unter verschiedenen Szenarien werfen.

Answer 2

Ja tut es. Es hilft anderen Entwicklern, vorbereitet zu sein und jede Ausnahme zu bewältigen, die auftreten könnte. Überlegen Sie, wie oft es Ihnen geholfen hat, sich auf Ausnahmen vorzubereiten, indem Sie die MSDN -Dokumentation durchlaufen.

Answer 3

Ich dokumentiere nur Ausnahmen, die behandelt werden könnten. Ist nicht sinnvoll, andere Ausnahmen zu dokumentieren. Meine Definition von Ausnahmen "Handhabung" ist, dass die Methode das versprochene Ergebnis liefern kann, indem sie die Ausnahme fangen.

Diese Antwort gilt also nur für diese Ausnahmen:

Wenn Sie das offene/geschlossene Prinzip folgen möchten, sollten Sie die Ausnahmen für die Schnittstelle und nicht die konkrete Klasse dokumentieren. Und alle Implementierungen müssen die gleiche Ausnahme auslegen, wenn das gleiche Szenario auftritt.