Come documentare un metodo che sovrascrive un altro metodo?

Question

Mi sono sempre chiesto come documentare un metodo che sovrascrive un messaggio da una classe base. Normalmente aggiungo un documento java a ciascun metodo pubblico e ad alcuni metodi privati ​​protetti.

Ma autogenerating un blocco di documentazione per un metodo di sostituzione in Eclipse produce qualcosa di simile:

/* 
* (non-Javadoc) 
* 
* @see javax.swing.JComponent#paintComponent(java.awt.Graphics) 
*/ 

È questo un buon modo per documentare l'override? Devo ereditare/copiare la documentazione dalla classe base?

Che cosa stai facendo come documentazione per questo caso speciale? Mi piacerebbe avere una panoramica delle pratiche che vengono utilizzate.

Answer 1

Ogni metodo - pubblico privato protetto - deve essere documentato che descrive ciò che fa. Dimenticatevi di ereditare la documentazione da una classe base - potete includere un link ad essa, se volete, ma finché l'informazione è lì che sovrascrive un metodo ereditato, l'altra persona è libera di cercarlo da sé. ASCIUTTO: non ripeterlo: documenta il metodo della classe base in un unico posto.

Non penso nemmeno che sia buono documentare quale metodo ha la precedenza, perché può cambiare e sarà difficile tenerlo aggiornato se si inseriscono nuove classi nella gerarchia tra la classe e la classe base . Semplicemente l'informazione che sovrascrive un metodo ereditato è sufficiente.

Se i metodi sono troppo complesse per documentare in poche righe di commento, poi si sono probabilmente troppo complesso e dovrebbe essere refactoring.

Answer 2

compresa l'annotazione @Override dovrebbe essere sufficiente per inviare un curioso sviluppatore al super.