Documentare le interfacce e la loro implementazione [chiuso]

Question

Sto decorando il mio codice C # con commenti in modo da poter produrre file di aiuto HTML.

Dichiaro e documento spesso interfacce. Ma le classi che implementano tali interfacce possono generare eccezioni specifiche a seconda dell'implementazione.

A volte, il client è consapevole solo delle interfacce che sta usando. Devo documentare le mie interfacce aggiungendo le possibili eccezioni che potrebbero essere generate dai suoi implementatori?

Devo creare / documentare eccezioni personalizzate in modo che gli implementatori di interfacce lancino queste invece di quelle del framework?

Spero sia chiaro!

Grazie

EDIT 4 gennaio 2010: ho deciso di scrivere un post sul blog su questo e le eccezioni personalizzate in .NET a http://blog.mikecouturier.com/2010/01/creating-custom-exceptions-in-net-right.html

Answer 1

Non sono sicuro di aver compreso appieno la tua domanda (e sono uno sviluppatore Java, non C #), ma sembra che tu stia chiedendo cosa sia essenzialmente un problema di polimorfismo: se qualcuno usa un metodo su un'interfaccia dichiarato di lanciare X e Y, cosa succede se un'implementazione genera Z?

Una cosa da seguire è il principio di conformità, che essenzialmente dice che un sottotipo dovrebbe essere conforme al comportamento del supertipo. Cioè, se stai documentando che il tuo metodo nell'interfaccia può generare solo eccezioni di un tipo (ad esempio, eccezioni puntatore nullo), il tuo contratto con i chiamanti è che questa è l'unica cosa che dovrebbero cercare. Se lanci qualcos'altro, potresti sorprenderli.

Documentare cose su un sottotipo specifico nel supertipo non è una buona idea poiché crea accoppiamenti inutili. Sarei più preoccupato per il fatto che un'implementazione potrebbe comportarsi in modo diverso rispetto alla dichiarazione poiché ciò potrebbe suggerire che la dichiarazione non sia sufficientemente definita.

Prova a pensare quali sono tutti i tipi di eccezioni che il tuo metodo potrebbe generare. Crea supertipi per loro, quindi dichiarali esplicitamente nel tuo metodo di interfaccia (ad esempio, questo metodo può generare alcune "eccezioni di calcolo"). Quindi, nell'implementazione, genera un'eccezione di calcolo con ulteriori dettagli oppure genera un sottotipo dell'eccezione di calcolo specifica dell'implementazione, ti conformerai comunque.

Answer 2

Sono d'accordo con tutto ciò che dice Uri: dovresti creare eccezioni personalizzate che possono essere estese se necessario, quindi un metodo che utilizza un parametro digitato sulla tua interfaccia può catturare quell'eccezione e catturare anche le eccezioni sottotipate.

Non crearli inutilmente, tuttavia, se esiste un'eccezione .Net Framework esistente che descrive la tua condizione di errore, utilizza

In termini di documentazione per gli implementatori, puoi utilizzare la sezione delle osservazioni dei commenti (supponendo che tu stia usando commenti XML) per descrivere cose come ti aspetteresti che gli implementatori facciano le cose. Ovviamente questo non è in alcun modo esecutivo ma può servire come utile guida quando uno sviluppatore utilizza la tua API