È necessario commentare i parametri ovvi? [duplicare]

Question

È necessario commentare i parametri ovvi? [duplicare]

#1 da (10 voti)
#2 da (2 voti)

1

La maggior parte delle volte, quando commento un metodo, seguirò questa struttura.

/**
 * Short description of what the method does
 *
 * @param {Type} name. Description of the variable.
 *
 * @return {Type}. What the return is.
 */

Ora se ho un metodo chiamato uploadData , che accetta un parametro, data , è ancora necessario dare a questo parametro una descrizione?

Mi rendo conto che necessario è un po 'soggettivo in questo caso, ma sono curioso di sapere quale sia il consenso generale. Per il momento ho dato loro tutte le descrizioni solo per mantenere la coerenza dei commenti, ma sembra che non sia mai stato necessario.

Se fa alcuna differenza, le lingue che uso sono Javascript, Java e PHP.

comments

posta TMH 18.09.2014 - 14:20

fonte

2 risposte

2

Descrivo solo i parametri quando fornisco al lettore informazioni . La definizione di informazione è "aggiunta alla conoscenza di qualcuno". Se la descrizione non si aggiunge alla conoscenza di qualcuno, allora non è informazione e la lascio fuori.

/**
* @param string username. The username. <--not providing information
*/

Anche Martin Fowler dice che se devi aggiungere un commento, probabilmente devi usare un nome migliore per il parametro. Questo dovrebbe valere anche per Javadoc.

risposta data 18.09.2014 - 14:43

fonte

Leggi altre domande sui tag comments

Cosa succede se non viene raggiunto lo Sprint Goal? La licenza è richiesta per i repository pubblici?

score 10 · Accepted Answer

Il fatto che l'unico parametro per una funzione upload abbia a che fare con i dati di caricamento non è degno di nota. Ciò che è vale la pena menzionare è ad es. in che formato si trova (è una stringa che fornisce il nome di un file locale? una stringa che costituisce i dati stessi? un flusso di byte?), quali restrizioni è soggetta a (illimitato? non più di 10 MB? solo 10 al giorno? ), se tutti i valori tecnicamente consentiti dal tipo sono a posto (è NULL okay? l'array vuoto va bene? deve essere una sequenza di byte UTF8 valida?), ecc.

Se tutti questi problemi sono chiaramente chiari a tutti i chiamanti del metodo (ad esempio se il parametro è un oggetto di caricamento appositamente costruito che garantisce che solo i dati validi possano entrare), andare avanti e lasciare il parametro non documentato. Ma spesso si scopre che sono precondizioni aggiuntive, ed è quasi sempre una buona idea renderle esplicite.