Commenti sul metodo sottoposto a override in Java

Question

Dovremmo commentare il metodo sottoposto a override oppure no? Se sì, allora se il commento sarà un documento Java o un semplice commento?

Answer 1

@ La risposta di SimonC spiega come l'utilità javadoc genera documentazione "ereditata" per i metodi sovrascritti.

È inoltre possibile inserire javadoc espliciti in un metodo di sostituzione e avranno la precedenza sui javadoc ereditati. Inoltre, se si inserisce il tag {@inheritDoc} nei javadoc espliciti del metodo override, i commenti ereditati verranno inclusi in quel punto.

Per rispondere a questo:

Dovremmo lasciare un commento, il metodo override o no? Se sì, allora se il commento sarà un documento Java o un semplice commento?

A mio parere, se il metodo di sostituzione affina la semantica documentati (contratto) del metodo override (o ... Dio non voglia ... rompe il contratto), allora questo merita di essere documentato nel metodo di sostituzione del javadocs. Tuttavia, se le differenze sono semplicemente "dettagli di implementazione", i commenti più semplici (o nessun commento) sono più appropriati.

(Tuttavia, la pratica di includere un commento "non javadoc" che rimanda il lettore al javadoc del metodo sottoposto a override è, IMO, uno spreco di spazio sullo schermo ... mentre sto leggendo il codice sorgente.)

Answer 2

Da How to Write Doc Comments for the Javadoc Tool:

automatico ri-uso del metodo commenti

È possibile evitare di ri-tipizzazione doc commenta da essere consapevoli di come lo strumento Javadoc duplicati (eredita) commenti per metodi che esegue l'override o implementa altri metodi . Ciò si verifica in tre casi: Quando un metodo in una classe sostituisce un metodo in una superclasse Quando un metodo in un'interfaccia sostituisce un metodo in un superinterfaccia Quando un metodo in una classe implementa un metodo in un'interfaccia Nella prima due casi, se un metodo m() sostituisce un altro metodo, lo strumento Javadoc creerà un sottotitolo "Sovrascrivi" in la documentazione per m(), con un collegamento al metodo su cui sta eseguendo l'override.

Nel terzo caso, se un metodo m() in una determinata classe implementa un metodo in un'interfaccia, lo strumento Javadoc sarà genererà un sottotitolo "specificato da" nella documentazione per m(), con un collegamento al metodo che sta implementando.

In tutti e tre questi casi, se il metodo m() non contiene commenti di documentazione o tag, lo strumento Javadoc sarà anche copiare il testo del metodo è priorità assoluta o attua nella documentazione generata per m(). Quindi, se la documentazione del metodo implementato sottoposto a override o è sufficiente, non è necessario aggiungere documentazione per per m(). Se si aggiunge qualsiasi commento o tag di documentazione a m(), il sottotitolo "Sostituzioni" o "Specificato da" e il collegamento verranno visualizzati, ma non verrà copiato il testo .