documentare eccezioni

Question

Ho la seguente interfaccia pubblica

public interface Bar{
   public void DoStuff();
}

con una classe interna di back-end

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

La domanda:

• Solo implementa l'interfaccia BarImpl Bar.
• BarImpl può generare eccezioni nel metodo DoStuff.

Ha senso per documentare queste eccezioni nel doc Bar.DoStuff xml?

Grazie in anticipo,

Answer 1

Sì -. Questo sarebbe il caso, anche se BarImpl non è l'unica implementor

L'esempio che mi piace usare è la classe flusso dove la astratto Leggi metodo liste un intero carico di eccezioni che gli utenti di un'istanza Stream potrebbe aspettarsi di essere gettato quando si utilizza questo metodo, e di conseguenza le implementatori di questa classe dovrebbe gettare in vari scenari.

Answer 2

Sì lo fa. Aiuta altri sviluppatori di essere preparati e di gestire qualsiasi eccezione che potrebbero verificarsi. Pensate quante volte ha aiutato a prepararsi per le eccezioni di passare attraverso la documentazione MSDN.

Answer 3

I Documento solo eccezioni che potrebbero essere gestiti. Non ha senso per documentare eventuali altre eccezioni. La mia definizione di "manipolazione" eccezioni è che il metodo in grado di fornire il risultato promesso dalla cattura l'eccezione.

Quindi, questa risposta è solo per le eccezioni:

Se si vuole seguire principio aperto / chiuso si dovrebbe documentare le eccezioni per l'interfaccia e non la classe concreta. E tutte le implementazioni devono lanciare la stessa eccezione quando si verifica lo stesso scenario.