È prassi corretta aggiungere commenti Javadoc nell'interfaccia e aggiungere commenti non Javadoc nell'implementazione?
La maggior parte degli IDE genera commenti non JavaDoc per le implementazioni quando si generano automaticamente commenti. Il metodo concreto non dovrebbe avere la descrizione?
Risposte:
Per metodi che sono solo implementazione (non override), certo, perché no, specialmente se sono pubblici.
Se hai una situazione prioritaria e stai per replicare qualsiasi testo, allora assolutamente no. La replica è un modo infallibile per causare discrepanze. Di conseguenza, gli utenti avrebbero una diversa comprensione del metodo in base al fatto che esaminino il metodo nel supertipo o nel sottotipo. Utilizzare @inheritDoco non fornire una documentazione: gli IDE utilizzeranno il testo più basso disponibile nella visualizzazione Javadoc.
Per inciso, se la tua versione di override aggiunge cose alla documentazione del supertipo, potresti essere in un mondo di guai. Ho studiato questo problema durante il mio dottorato di ricerca e ho scoperto che in generale le persone non saranno mai a conoscenza delle informazioni extra nella versione prioritaria se invocano attraverso un supertipo.
Affrontare questo problema era una delle caratteristiche principali dello strumento prototipo che ho creato: ogni volta che invocavi un metodo, ottieni un'indicazione se il suo obiettivo o qualsiasi potenziale obiettivo prioritario conteneva informazioni importanti (ad esempio, un comportamento in conflitto). Ad esempio, quando invocate put su una mappa, vi è stato ricordato che se la vostra implementazione è una TreeMap, i vostri elementi devono essere comparabili.
Sia l'implementazione che l'interfaccia dovrebbero avere javadoc. Con alcuni strumenti è possibile ereditare la documentazione dell'interfaccia con la parola chiave @inheritDoc.
/**
* @inheritDoc
*
* This implementation is very slow when b equals 3.
*/
public foo(int b)
{ ... }{@inheritDoc}e funziona solo se non hai @Overrideprima l'annotazione
Un po 'di buona pratica è mettere
/**
* {@inheritDoc}
*/come javadoc dell'implementazione (a meno che non ci sia qualcosa in più da spiegare sui dettagli dell'implementazione).
In genere, quando si sovrascrive un metodo, si aderisce al contratto definito nella classe / interfaccia di base, quindi non si desidera comunque modificare il javadoc originale. Pertanto l'uso di @inheritDoco il @seetag menzionato in altre risposte non è necessario e in realtà serve solo come rumore nel codice. Tutti gli strumenti sensibili ereditano il metodo javadoc dalla superclasse o dall'interfaccia come specificato qui :
Inherit from classes and interfaces - Inheriting of comments occurs in all
three possible cases of inheritance from classes and interfaces:
- When a method in a class overrides a method in a superclass
- When a method in an interface overrides a method in a superinterface
- When a method in a class implements a method in an interfaceIl fatto che alcuni strumenti (ti sto guardando, Eclipse!) Li generano per impostazione predefinita quando si sovrascrive un metodo è solo un triste stato di cose, ma non giustifica l'ingombro del codice con rumore inutile.
Ovviamente può esserci il caso opposto, quando si desidera effettivamente aggiungere un commento al metodo di sostituzione (di solito alcuni dettagli di implementazione aggiuntivi o rendere il contratto un po 'più rigoroso). Ma in questo caso, non vuoi quasi mai fare qualcosa del genere:
/**
* {@inheritDoc}
*
* This implementation is very, very slow when b equals 3.
*/Perché? Perché il commento ereditato può essere molto lungo. In tal caso, chi noterà la frase in più alla fine dei 3 lunghi paragrafi ?? Invece, scrivi semplicemente il pezzo del tuo commento e basta. Tutti gli strumenti javadoc mostrano sempre una sorta di collegamento Specificato da su cui è possibile fare clic per leggere il commento della classe base. Non ha senso mescolarli.
@see Genera un collegamento alla descrizione nell'interfaccia. Ma penso che sia bene aggiungere anche alcuni dettagli sull'implementazione.
@seecollegamento ai metodi di interfaccia è una buona pratica ed è sufficiente nella maggior parte dei casi. Quando copi javadoc dal metodo dell'interfaccia all'implementazione concreta, duplica semplicemente le informazioni e possono diventare rapidamente incoerenti. Tuttavia, qualsiasi informazione aggiuntiva sull'implementazione dovrebbe essere aggiunta a javadoc.
Sjoerd dice correttamente che sia l'interfaccia che l'implementazione dovrebbero avere JavaDoc. L'interfaccia JavaDoc dovrebbe definire il contratto del metodo: cosa dovrebbe fare il metodo, quali input richiede, quali valori dovrebbe restituire e cosa dovrebbe fare in caso di errore.
La documentazione di implementazione dovrebbe annotare estensioni o restrizioni del contratto e anche dettagli appropriati dell'implementazione, in particolare le prestazioni.
Per il bene del javadoc generato sì, importa. Se dichiari riferimenti a un'implementazione concreta utilizzando solo l'interfaccia, non lo fa poiché i metodi dell'interfaccia verranno recuperati dall'IDE.