Codice auto-documentante vs Javadocs?

Recentemente ho lavorato sul refactoring di parti della base di codice con cui sto attualmente trattando - non solo per capirlo meglio da solo, ma anche per renderlo più facile per gli altri che stanno lavorando al codice.

Tendo a appoggiarmi al lato di pensare che il codice di auto-documentazione sia carino . Penso solo che sia più pulito e se il codice parla da solo, beh ... Fantastico .

D'altra parte abbiamo documentazione come javadocs. Mi piace anche questo, ma c'è un certo rischio che i commenti qui diventino obsoleti (così come i commenti in generale). Tuttavia, se sono aggiornati, possono essere estremamente utili per dire, comprendere un algoritmo complesso.

Quali sono le migliori pratiche per questo? Dove traccia il confine tra il codice autocompensante e javadocs?

Il codice auto-documentante (e i commenti nel codice) e i commenti Javadoc hanno due destinatari molto diversi.

Il codice e i commenti che rimangono nel file di codice sono destinati agli sviluppatori. Vuoi affrontare le loro preoccupazioni qui: rendi più facile capire cosa fa il codice e perché il codice è così com'è. L'utilizzo di nomi di variabili, metodi, classi e così via appropriati (codice auto-documentante) accoppiato con commenti ottiene questo risultato.

I commenti Javadoc sono in genere per gli utenti dell'API. Questi sono anche sviluppatori, ma non si preoccupano della struttura interna del sistema, ma solo delle classi, dei metodi, degli input e degli output del sistema. Il codice è contenuto in una scatola nera. Questi commenti dovrebbero essere usati per spiegare come svolgere determinate attività, quali sono i risultati previsti delle operazioni, quando vengono generate eccezioni e cosa significano i valori di input. Dato un set di documentazione generato da Javadoc, dovrei essere in grado di comprendere appieno come utilizzare le tue interfacce senza mai guardare una riga del tuo codice.

Il codice dice come . I commenti dicono perché , e forse anche perché no .

Il tuo compito è fornire sia ai lettori futuri che ai manutentori del tuo codice. Inserisci tutto ciò che puoi nel codice e il resto nei commenti.

Nota che le cose più difficili da catturare sono le decisioni di progettazione - ricorda anche quelle.

L'uso di Javadocs non fa davvero la differenza - poiché i documenti generati contengono il nome delle tue funzioni insieme al testo dei commenti, non c'è assolutamente alcun motivo per cui dovresti ripetere qualcosa nei commenti che sia chiaro dal nome della funzione stessa.

Se, d'altra parte, hai una funzione in cui devi prima guardare l'implementazione per capire a cosa serve (quindi non rendere queste informazioni disponibili a Javadocs), allora il codice è IMHO non auto-documentante, non importa quanto sia chiara l'implementazione.

Penso che con javadocs le cose siano le stesse di qualsiasi altra documentazione - la regola principale è:

segui il pubblico

Non molte persone di leggere i tuoi javadocs? Se sì, ha senso investire gli sforzi per farlo nel modo giusto.

I tuoi lettori tendono a saltare la lettura del codice a favore dello studio di javadocs? Se sì, ha il doppio del senso spendere gli sforzi per scriverlo bene.

• Questo è esattamente il caso della documentazione JDK . Immagino che Sun / Oracle abbiano speso molti sforzi su questi e sembrano avere un buon rimborso nei documenti API utilizzati molto dalla comunità.

Adesso è il tuo caso? In caso contrario, pensa due volte se gli sforzi investiti in javadocs sono giustificati.

Come già indicato sopra, ascolta il pubblico per scoprire la strada.

• Se senti lamentele attive su documentazione insufficiente, considera di investire per migliorarla.
   
  Se, d'altra parte, tutto ciò che senti sono gli sviluppatori che si lamentano delle regole del cervello, costringendoli a perdere tempo a scrivere inutilmente, beh, allora è molto probabile che i tuoi sforzi javadocs siano come investire in mutui subprime . Pensa invece a investimenti migliori.

Voglio solo commentare la preoccupazione che i commenti di Javadoc potrebbero essere obsoleti. Mentre @JonathanMerlet ha ragione nel dire che Javadoc dovrebbe essere stabile, puoi anche aiutare rivedendo Javadoc e commenti, nonché codice durante la revisione tra pari. I commenti corrispondono a ciò che sta facendo il codice? In caso contrario, il che è errato e insistere con lo sviluppatore per risolverlo. Cerca di incoraggiare altri sviluppatori a fare lo stesso. Ciò consente di mantenere aggiornati non solo la documentazione esterna (commenti Javadoc), ma anche eventuali commenti di codice regolari. Questo aiuta gli sviluppatori che si presentano dopo il refactoring a capire il codice più rapidamente e facilmente e rendono il mantenimento molto più semplice in futuro.

Penso che javadocs sia appropriato per le parti che dovrebbero rimanere stabili (API) in modo da ridurre al minimo il rischio che i commenti scadano, mentre il codice di auto-documentazione è ottimo per ciò che è soggetto a frequenti cambiamenti (implementazione). Naturalmente, le API possono cambiare durante il corso del progetto, ma avere l'intestazione appena prima della dichiarazione, mantenere entrambi sincronizzati non è così difficile (rispetto ai commenti su più righe che spiegano diverse righe di codice)