Voglio scrivere Javadoc in modo SECCO. Ma il documento dell'oracolo su Javadoc dice di scrivere di nuovo la stessa cosa nel commento del metodo di sovraccarico. Non posso evitare la ripetizione?
Voglio scrivere Javadoc in modo SECCO. Ma il documento dell'oracolo su Javadoc dice di scrivere di nuovo la stessa cosa nel commento del metodo di sovraccarico. Non posso evitare la ripetizione?
Risposte:
Cospargo le {@inheritDoc}direttive qua e là nei miei commenti su Javadoc durante l'override dei metodi dalle superclassi o l'implementazione di metodi definiti dall'interfaccia.
Questo funziona bene almeno per me, evita la ripetizione nel codice sorgente e puoi ancora aggiungere informazioni specifiche al particolare commento di Javadoc se è necessario. Non considero il fatto che il commento Javadoc stesso sia abbastanza nudo per essere un problema quando tutto ciò che serve in un IDE decente è passare il mouse sul nome dell'identificatore associato per ottenere il Javadoc renderizzato con riferimenti e tutto il resto.
Il punto della documentazione è illuminare i futuri utenti di un articolo. Questo è in parte per comodità dell'autore, in modo che 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.
Come tale, il punto dovrebbe essere la chiarezza, al contrario di convenienza per l'autore. Non puoi aspettarti che le persone cacciano su e giù attraverso la tua documentazione API perché sei essenzialmente troppo pigro per ripeterti. Succhialo: Javadoc sarà ripetitivo.
Detto questo, non c'è motivo, se sei intelligente, non puoi scrivere un programma che inserisca i commenti nel tuo codice in base a marcatori o altri criteri. Potrebbe essere più un problema di quanto valga la pena. O no.