Voglio scrivere Javadoc in modo ASCIUTTO. Ma il documento dell'oracolo su Javadoc dice di scrivere di nuovo la stessa cosa nel metodo di overload commento. Non posso evitare la ripetizione?
Voglio scrivere Javadoc in modo ASCIUTTO. Ma il documento dell'oracolo su Javadoc dice di scrivere di nuovo la stessa cosa nel metodo di overload commento. Non posso evitare la ripetizione?
Spruzzo {@inheritDoc} di direttive qua e là nei miei commenti Javadoc quando eseguo l'override dei metodi da superclassi o implementando metodi definiti dall'interfaccia.
Almeno questo funziona per me, evita la ripetizione nel codice sorgente e puoi comunque aggiungere informazioni specifiche al particolare commento Javadoc se c'è la necessità di farlo. Non considero il fatto che il commento Javadoc in sé sia abbastanza semplice per essere un problema quando tutto ciò che serve in un IDE decente è passare il mouse sopra il nome dell'identificatore associato per ottenere il Javadoc reso con riferimenti e tutto.
Il punto della documentazione è quello di illuminare i futuri utenti di un oggetto. Questo è in parte per la comodità dell'autore, in modo che lui o lei non debba essere contattato ogni volta che qualcuno non riesce a capire come funziona la cosa. Principalmente, tuttavia, è a beneficio delle persone che hanno bisogno di usare o supportare la cosa.
In quanto tale, il punto dovrebbe essere la chiarezza, al contrario della convenienza per l'autore. Non ci si può aspettare che la gente dia la caccia alla documentazione della tua API perché sei stato troppo pigro per ripeterti. Succhialo: Javadoc sarà ripetitivo.
Detto questo, non c'è motivo, se sei intelligente, non puoi scrivere un programma in grado di incollare commenti nel tuo codice basato su indicatori o altri criteri. Potrebbe essere più difficile di quello che vale. Oppure no.
Leggi altre domande sui tag comments documentation dry javadocs