Dovrebbero i commenti metodo / classe essere coerentemente applicate o solo su una base bisogno?

Question

Per coerenza, ho sempre applicato commenti (sotto forma di un JavaDoc) a tutti i metodi e le classi, anche se sono semplici getter e setter metodi o classi wrapper molto piccoli. Ma sto anche cercando di scrivere codice auto-documentazione che spesso fa commenti superflui; vale a dire i commenti di scrittura solo quando necessario (e prima di farlo, prova a riscrivere il codice in modo che non è necessario il commento a tutti). Quindi, questi due approcci sembrano essere contraddittorie tra loro.

Così dovrebbe commenti che descrivono un metodo o una classe di essere applicato in modo coerente, o dovrebbe tali osservazioni essere scritto solo quando il significato non è del tutto chiaro dalla definizione?

Answer 1

Un semplice test del nove sarebbe quello di controllare se la classe ha più commenti che il codice. Se yest allora significa che il codice è troppo complesso e difficile da usare per chiunque.

Quindi è meglio scrivere di sé il codice esplicativo. Inoltre v'è alcun bisogno di commenti di scrittura per le cose che sono evidenti come setter e getter.

Quindi, vorrei andare con tali osservazioni essere scritto solo quando il significato non è del tutto chiaro dalla definizione.

Answer 2

ho usato per creare codice per ogni metodo, ma ora ho solo creare documentazione quando le osservazioni aggiungere qualche informazione in più rispetto al codice stesso.

Ecco una domanda su un argomento simile con un sacco di risposte. Come si evolve codice c'è una possibilità che l'aggiornamento della documentazione è "dimenticato". Riferendosi alla domanda nella documentazione cattivo collegamento è peggio di alcuna documentazione a tutti.