Documentazione API e “limiti di valore”:corrispondono?

Question

Vedi spesso nella documentazione API (come ad esempio in "javadoc delle funzioni pubbliche") la descrizione dei "limiti di valore" oltre alla documentazione classica?

Nota: Non ne sto parlando commenti all'interno del codice

Per "limiti di valore" intendo:

• un parametro può supportare un valore nullo (o una stringa vuota o...)?
• un "valore restituito" può essere nullo o è garantito che non sarà mai nullo (o può essere "vuoto" o...)?

Campione:

Quello che vedo spesso (senza avere accesso al codice sorgente) è:

/**
 * Get all readers name for this current Report. <br />
 * <b>Warning</b>The Report must have been published first.
 * @param aReaderNameRegexp filter in order to return only reader matching the regexp
 * @return array of reader names
 */
 String[] getReaderNames(final String aReaderNameRegexp);

Cosa io piacerebbe vedere sarebbe:

/**
 * Get all readers name for this current Report. <br />
 * <b>Warning</b>The Report must have been published first.
 * @param aReaderNameRegexp filter in order to return only reader matching the regexp 
 * (can be null or empty)
 * @return array of reader names 
 * (null if Report has not yet been published, 
 *  empty array if no reader match criteria, 
 *  reader names array matching regexp, or all readers if regexp is null or empty)
 */
 String[] getReaderNames(final String aReaderNameRegexp);

Il mio punto è:

Quando utilizzo una libreria con una funzione getReaderNames() al suo interno, spesso non ho nemmeno bisogno di leggere la documentazione dell'API per indovinare cosa fa.Ma devo essere sicuro come usarlo.

La mia unica preoccupazione quando voglio utilizzare questa funzione è:cosa dovrei aspettarmi in termini di parametri e valori restituiti?Questo è tutto ciò che devo sapere per impostare in modo sicuro i miei parametri e testare in sicurezza il valore restituito, ma non vedo quasi mai questo tipo di informazioni nella documentazione dell'API...

Modificare:

Ciò può influenzare l'utilizzo o meno eccezioni controllate o non controllate.

Cosa ne pensi ?limiti di valore e API, vanno insieme o no?

Answer 1

penso che loro Potere appartengono insieme ma non necessariamente Avere appartenere insieme.Nel tuo scenario, sembra logico che i limiti siano documentati in modo tale da apparire nella documentazione API e nell'intellisense generati (se il linguaggio/IDE lo supporta).

Penso che dipenda anche dalla lingua.Ad esempio, Ada ha un tipo di dati nativo che è un "intero limitato", in cui definisci una variabile intera e indichi esplicitamente che sarà solo (e sempre) entro un determinato intervallo numerico.In tal caso, il tipo di dati stesso indica la restrizione.Dovrebbe essere comunque visibile e rilevabile tramite la documentazione API e IntelliSense, ma non dovrebbe essere qualcosa che uno sviluppatore deve specificare nei commenti.

Tuttavia, linguaggi come Java e C# non hanno questo tipo di intero ristretto, quindi lo sviluppatore dovrebbe specificarlo nei commenti se si trattasse di informazioni che dovrebbero diventare parte della documentazione pubblica.

Answer 2

Penso che questo tipo di condizioni al contorno appartengano sicuramente all'API.Tuttavia, vorrei (e spesso lo faccio) fare un ulteriore passo avanti e indicare COSA significano quei valori nulli.O indico che genererà un'eccezione oppure spiego quali sono i risultati attesi quando viene passato il valore limite.

È difficile ricordarsi di farlo sempre, ma è una buona cosa per gli utenti della tua classe.È anche difficile mantenerlo se il contratto presentato dal metodo cambia (come i valori nulli vengono modificati per non essere consentiti)...devi essere diligente anche per aggiornare i documenti quando cambi la semantica del metodo.

Answer 3

Domanda 1

Vedi spesso nella documentazione API (come ad esempio in "javadoc delle funzioni pubbliche") la descrizione dei "limiti di valore" oltre alla documentazione classica?

Quasi mai.

Domanda 2

La mia unica preoccupazione quando voglio utilizzare questa funzione è:cosa dovrei aspettarmi in termini di parametri e valori restituiti?Questo è tutto ciò che devo sapere per impostare in modo sicuro i miei parametri e testare in sicurezza il valore restituito, ma non vedo quasi mai questo tipo di informazioni nella documentazione dell'API...

Se utilizzassi una funzione non correttamente mi aspetterei a RuntimeException lanciato dal metodo o a RuntimeException in un'altra parte (a volte molto lontana) del programma.

Commenti come @param aReaderNameRegexp filter in order to ... (can be null or empty) mi sembra un modo da implementare Progettazione per contratto in un linguaggio umano interiore Javadoc.

L'utilizzo di Javadoc per applicare Design by Contract è stato utilizzato da iContract, ora resuscitato in JcontractS, che ti consente di specificare invarianti, precondizioni, postcondizioni, in modo più formalizzato rispetto al linguaggio dell'essere umano.

Domanda 3

Ciò può influenzare l'utilizzo o meno delle eccezioni selezionate o non controllate.Cosa ne pensi ?limiti di valore e API, vanno insieme o no?

Il linguaggio Java non dispone della funzionalità Design by Contract, quindi potresti essere tentato di utilizzarlo Execption ma sono d'accordo con te sul fatto di cui devi essere consapevole Quando scegliere le eccezioni selezionate e non selezionate.Probabilmente potresti usare unchecked IllegalArgumentException, IllegalStateException, oppure potresti utilizzare il test unitario, ma il problema principale è come comunicare ad altri programmatori che tale codice riguarda Design By Contract e dovrebbe essere considerato come un contratto prima di modificarlo troppo alla leggera.

Answer 4

Penso che lo facciano e hanno sempre inserito commenti nei file header (c++) di conseguenza.

Oltre ai commenti validi di input/output/ritorno, noto anche quali eccezioni probabilmente verranno lanciate dalla funzione (poiché spesso desidero utilizzare il valore restituito per... beh restituendo un valore, preferisco le eccezioni rispetto ai codici di errore)

//File:
// Should be a path to the teexture file to load, if it is not a full path (eg "c:\example.png") it will attempt to find the file usign the paths provided by the DataSearchPath list
//Return: The pointer to a Texture instance is returned, in the event of an error, an exception is thrown. When you are finished with the texture you chould call the Free() method.
//Exceptions:
//except::FileNotFound
//except::InvalidFile
//except::InvalidParams
//except::CreationFailed
Texture *GetTexture(const std::string &File);

Answer 5

@Fire Lancer:Giusto!Ho dimenticato le eccezioni, ma mi piacerebbe vederle menzionate, in particolare l'eccezione "runtime" non controllata che questo metodo pubblico potrebbe lanciare

@Mike Stone:

devi essere diligente anche per aggiornare i documenti quando cambi la semantica del metodo.

Mmmm spero davvero che il documentazione API pubblica viene almeno aggiornato ogni volta che avviene una modifica, che influisce sul contratto della funzione.In caso contrario, la documentazione API potrebbe essere eliminata del tutto.

Per aggiungere cibo ai tuoi pensieri (e andare con @Scott Dorman), mi sono imbattuto in questo il futuro delle annotazioni Java7

Che cosa significa questo ?Che certe "condizioni al contorno", piuttosto che essere nella documentazione, dovrebbero essere meglio nell'API stessa e utilizzate automaticamente, al momento della compilazione, con il codice generato "assert" appropriato.

In questo modo, se nell'API è presente un "@CheckForNull", l'autore della funzione potrebbe farla franca senza nemmeno documentarlo!E se la semantica cambia, la sua API rifletterà tale modifica (come "non più @CheckForNull" per esempio)

Questo tipo di approccio suggerisce che la documentazione, per le “condizioni al contorno”, sia un vantaggio extra piuttosto che una pratica obbligatoria.

Tuttavia, ciò non copre i valori speciali dell'oggetto restituito di una funzione.Per questo, a completare la documentazione è ancora necessaria.