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

Uno degli sviluppatori del mio team ritiene che sia necessario scrivere un commento javadoc per OGNI parametro nella firma di un metodo. Non penso che ciò sia necessario, e in effetti penso che possa persino essere dannoso.

Prima di tutto, penso che i nomi dei parametri dovrebbero essere descrittivi e auto-documentati. Se non è immediatamente ovvio a cosa servono i tuoi parametri, probabilmente lo stai facendo in modo sbagliato. Tuttavia, capisco che a volte non è chiaro a cosa serva un parametro, quindi in quei casi sì, dovresti scrivere un commento javadoc che spieghi il parametro.

Ma penso che non sia necessario farlo per OGNI parametro. Se è già ovvio lo scopo del parametro, il commento javadoc è ridondante; stai solo creando lavoro extra per te stesso. Inoltre, stai creando lavoro extra per chiunque debba mantenere il tuo codice. I metodi cambiano nel tempo e mantenere i commenti è quasi importante quanto mantenere il tuo codice. Quante volte hai visto un commento come "X fa Y per motivi di Z" solo per vedere che il commento è obsoleto e in effetti il ​​metodo non accetta più nemmeno il parametro X? Succede sempre, perché le persone dimenticano di aggiornare i commenti. Direi che un commento fuorviante è più dannoso di nessun commento. E quindi c'è il pericolo di commentare eccessivamente: creando una documentazione non necessaria, tu '

Tuttavia, rispetto l'altro sviluppatore del mio team e accetto che forse ha ragione e io ho torto. Ecco perché vi porgo la mia domanda, colleghi sviluppatori: è davvero necessario scrivere un commento javadoc per OGNI parametro? Supponiamo qui che il codice sia interno alla mia azienda e non venga utilizzato da terzi.

Le annotazioni Javadoc (e, in Microsoft Word, XMLDoc) non sono commenti , sono documentazione .

I commenti possono essere sparsi come vuoi che siano; supponendo che il tuo codice sia leggibile a metà, quindi i commenti ordinari sono semplicemente indicazioni per aiutare i futuri sviluppatori a comprendere / mantenere il codice che stanno già fissando da due ore.

La documentazione rappresenta un contratto tra un'unità di codice e i suoi chiamanti. Fa parte dell'API pubblica. Supponi 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 utilizzarlo per uno scopo di il loro.

I nomi degli argomenti / parametri non sono mai autoesplicativi. Pensi sempre che lo siano quando hai passato il giorno passato a lavorare sul codice, ma prova a tornarci dopo una vacanza di 2 settimane e vedrai quanto sono davvero inutili.

Non fraintendermi: è importante scegliere nomi significativi per variabili e argomenti. Ma questo è un problema di codice, non un problema di documentazione. Non prendere la frase "autocertificazione" troppo alla lettera; ciò si intende 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 utilizza il tuo codice, rivedendo l'API direttamente nel file di origine o in un file doc generato (ad esempio output doxygen). Le incoerenze portano generalmente alla confusione, che porta al tempo speso a scavare attraverso la fonte per capire perché qualcosa non è stato commentato, il che porta a sprecare tempo che avrebbe potuto essere evitato se il parametro fosse stato commentato in primo luogo.

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

Detto questo, se l'altro sviluppatore sta sottolineando l'importanza di documentare tutto, è necessario porre altrettanta enfasi (se non di più) sull'aggiornamento della documentazione. Come hai affermato, non c'è molto peggio che avere commenti obsoleti (altrettanto male, se non peggio dei documenti omessi).

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

Ciò significa che gli sviluppatori non dovrebbero perdere tempo a documentare parametri evidenti e valori di ritorno, giusto?

Bene, analizziamolo.

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

Se selezioniamo e scegliamo, i costi sono:

• Avere e vincere la discussione con gli altri sviluppatori del tuo team che pensano che tutto dovrebbe essere documentato.
• Per ogni parametro, determinare se questo deve o non deve essere documentato.
• Altre discussioni con il tuo team quando qualcuno ha un'opinione diversa sull'opportunità di documentare un parametro.
• Il tempo passa a cercare il codice e a ricercare quando un parametro ritenuto autoesplicativo risulta non essere così.

Quindi, sarei propenso a documentare tutto. Il rovescio della medaglia è definito, ma è contenuto.

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

Per quanto riguarda la corretta manutenzione di Javadoc, è necessario utilizzare strumenti per lo sviluppo che possano esserti utili. Mi viene in mente Eclipse . Naturalmente, se è importante, è necessario assicurarsi che tutti i membri del team facciano la propria parte per mantenere il codice, inclusi i commenti.

Non dimenticare che javadoc può essere reso visibile separatamente dal codice, ad esempio l' API Java stessa. Non includendo javadoc per ogni parametro in un metodo, si rappresenta in modo errato il metodo e il modo in cui potrebbe essere utilizzato.

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

Se questo codice pubblico (ovvero codice destinato ad altri, come un API), sì, documenta ogni singolo parametro. Non dare per scontato che il lettore sia a conoscenza del progetto tanto quanto te. In caso contrario, spetta a te e al tuo team prendere le proprie decisioni.