E 'necessario scrivere un commento javadoc per OGNI parametro nella firma di un metodo?

Le annotazioni Javadoc (e, nelle parole Microsoft, XMLDoc) non sono commenti , sono documentazione .

Commenti possono essere scarsi come vuoi; supponendo che il tuo codice sia leggibile a metà, i normali commenti sono solo dei segnali per aiutare i futuri sviluppatori a capire / mantenere il codice che stanno già guardando da due ore.

La documentazione rappresenta un contratto tra un'unità di codice e i suoi chiamanti. Fa parte dell'API pubblica. Supponiamo sempre che Javadoc / XMLdoc finisca in un file di aiuto o in un popup di completamento automatico / intellisense / completamento del codice e venga osservato da persone che non stanno esaminando gli interni del tuo codice ma desiderano semplicemente usarlo per qualche scopo.

I nomi degli argomenti / parametri sono mai auto-esplicativi. È sempre pensa che sono quando hai passato il giorno passato a lavorare sul codice, ma prova a tornare ad esso dopo una vacanza di 2 settimane e vedrai quanto sono veramente inutili.

Non fraintendermi: è importante scegliere nomi significativi per variabili e argomenti. Ma questa è una preoccupazione del codice, non un problema di documentazione. Non prendere la frase "autodocumentazione" troppo alla lettera; inteso nel contesto della documentazione interna (commenti), non della documentazione esterna (contratti).

O commentare tutto o commentare nulla (ovviamente commentare tutto è una scelta molto migliore). Pensa a qualcuno che usa il tuo codice, o riesamina la tua API direttamente nel tuo file sorgente o in un file doc generato (ad esempio, output doxygen). Generalmente le incoerenze portano a confusione, il che porta a dedicare tempo a scavare attraverso la fonte per capire perché qualcosa non è stato commentato, il che porta a tempo perso che avrebbe potuto essere evitato se il parametro fosse stato appena commentato nel primo posto.

Ricorda: qualcosa che ha senso per te può essere interpretato in modo completamente diverso da qualcun altro, non importa quanto tu pensi che sia banale (pensa a qualcuno che non è così strong nella lettura dell'inglese e cerca di capire il tuo codice).

Detto questo, se l'altro sviluppatore sta sottolineando l'importanza di documentare tutto, allora altrettanta enfasi (se non di più) deve essere messo al mantenimento della documentazione aggiornata. Come hai affermato, non c'è niente di peggio che avere commenti obsoleti (altrettanto male, se non peggio dei documenti omessi).

Se stai scrivendo Javadoc comunque, potresti anche scriverlo completamente, includendo anche i parametri "ovvi". Potrebbero essere ovvi per te o per l'altro sviluppatore, ma chiunque sia nuovo a guardarlo trarrebbe beneficio dalla conoscenza dell'intenzione di ciascun parametro.

Come per mantenere Javadoc correttamente, è necessario utilizzare gli strumenti per il tuo sviluppo che ti aiutano in questo. Eclipse mi viene in mente. Ovviamente, se è importante, devi assicurarti che tutti i membri del team facciano la loro parte per mantenere il codice, inclusi i commenti.

Partiamo dal presupposto che i cicli di sviluppo sono la risorsa che stiamo cercando di conservare.

Quindi questo significa che gli sviluppatori non dovrebbero perdere tempo a documentare parametri auto-evidenti e restituire valori, giusto?

Bene, scomporlo.

Se documentiamo tutto, assumendo che i commenti marginali siano davvero banali e non richiedano alcun pensiero o ricerca, il costo è il tempo aggiunto per digitare effettivamente il commento e correggere gli errori di battitura.

Se selezioniamo e selezioniamo, i costi sono:

• Avere e vincere l'argomento con gli altri sviluppatori della tua squadra che pensano che tutto debba essere documentato.
• Per ogni parametro, determinare se questo dovrebbe o non dovrebbe essere documentato.
• Ulteriori argomenti con il tuo team quando qualcuno ha un'opinione diversa sulla necessità o meno di documentare un parametro.
• Tempo trascorso a cercare il codice e a ricercare quando un parametro ritenuto auto-esplicativo risulta non essere così.

Quindi, sarei incline a documentare semplicemente tutto. Lo svantaggio è definito, ma è contenuto.

Non dimenticare che javadoc può essere reso visibile mentre è separato dal codice, primo esempio essendo l'API Java stesso. Non includendo javadoc per ogni parametro in un metodo, si sta travisando il metodo e come potrebbe essere utilizzato.

'necessario' è completamente soggettivo. Penso che quello che stai chiedendo è, 'nella tua situazione, dovrebbe aggiungere un commento javadoc'. Non conoscendo l'ambito o il contesto della tua app, come possiamo sapere che cosa è appropriato per te?

Se questo codice di contatto pubblico (cioè, codice destinato ad altri per l'accesso, ad esempio un API) allora sì, documenta ogni singolo parametro. Non dare per scontato che il lettore sia a conoscenza del progetto tanto quanto te. Altrimenti, sta a te e al tuo team prendere le vostre decisioni.