I commenti del metodo dovrebbero essere scritti come se tutto funzionasse?

Question

I commenti del metodo dovrebbero essere scritti come se tutto funzionasse?

#1 da (4 voti)
#2 da (3 voti)
#3 da (0 voti)

0

Se ho un metodo per cercare un indirizzo email valido in un array, è possibile:

Restituisce l'indirizzo email
Restituisce false se non è stata trovata un'email.
Genera un'eccezione se è stata trovata un'email, ma non era valida.

Il commento del metodo dovrebbe essere scritto come se funzionasse sempre, o dovrebbe indicare che potrebbe fallire? Ad esempio:

/**
 * Attempts to return the email address from $data.
 * @param Array $data
 * @return Boolean
 * @throws My_Custom_Exception_InvalidEmailAddress
 */

vs

/**
 * Returns the email address in the $data.
 * @param Array $data
 * @return Boolean
 * @throws My_Custom_Exception_InvalidEmailAddress 
 *      Throw if an email key is found in $data, but the value is empty
 *      or if the value doesn't pass the Zend_Validate_Email check.
 */

In generale, vado secondo la regola di, se ho scritto un po 'di "lancio nuovo ..." nel metodo, lo scriverò più come il primo esempio, perché so che ci sono buone probabilità che il metodo non farà ciò che dice il commento, ma lo puoi dire con l'annotazione @throws, quindi sembra un po 'inutile.

È o lo stile di commento "preferito", o è più solo un caso di essere coerenti in tutto il progetto?

comments

posta TMH 26.01.2016 - 12:06

fonte

3 risposte

4

"Genera InvalidEmailAddress se viene trovato un indirizzo email non valido" sembra in qualche modo ridondante.

Commentando ciò che costituisce "non valido" sarebbe un uso migliore del blocco dei commenti, ma altrimenti commenta il minimo necessario per capire cosa è inteso, più documentazione metti in più manutenzione che richiederà come modifiche al codice.

risposta data 26.01.2016 - 12:10

fonte

0

È, come sempre, soprattutto per mantenerlo coerente.

Si potrebbe obiettare che se si lancia un FoundInvalidEmailAddressException spuntato non sarà nemmeno necessario il throw perché fornisce informazioni duplicate che il compilatore dirà comunque, ma lo scriverei in questo modo:

/**
 * Returns the email address in the $data.
 * @param  Array $data //what format do you expect data to be? 
 *         eg. [username, password]? [username, email]?
 * @return Boolean true if the email is found and valid, false otherwise
 * @throws InvalidEmailAddressException If there is an email for $data, 
 *         but it fails validation. An email is invalid if...
 */

risposta data 26.01.2016 - 12:17

fonte

Leggi altre domande sui tag comments

Eliminando i casi cattivi in se ottenere un codice migliore Perché HTML5 si è sbarazzato delle applicazioni Rich Desktop? [chiuso]

score 3 · Accepted Answer

Lanciare un'eccezione, per definizione, significa che il metodo non restituisce ciò che deve essere restituito. Se hai un'annotazione @throws (e dovresti, sempre!), Allora il fatto che il valore di ritorno promesso potrebbe non accadere è completamente ovvio. Non c'è nulla di guadagnato complicando la documentazione per dire "Tries to return" o qualcosa del genere.

Ciò che dovrebbe scrivere sempre è, nel modo più preciso possibile, in quali circostanze ciò accadrà. non importa se l'effettiva throw è nel tuo codice o nel codice di terze parti, l'unica differenza è che di solito sei un po 'più certo delle circostanze esatte se è nel tuo codice.