Codice auto-documentante vs Javadocs?

Il codice di auto-documentazione (e commenti nel codice) e i commenti Javadoc hanno due segmenti di pubblico molto diversi.

Il codice e i commenti che rimangono nel file di codice sono per gli sviluppatori. Desiderate affrontare le loro preoccupazioni qui - semplificare la comprensione di cosa fa il codice e perché il codice è così com'è. L'uso di nomi di variabili, metodi, classi e così via (codice di autocertificazione) accoppiati con i commenti raggiunge 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, solo delle classi, dei metodi, degli input e degli output del sistema. Il codice è contenuto in una scatola nera. Questi commenti dovrebbero essere utilizzati per spiegare come eseguire determinate attività, quali sono i risultati previsti delle operazioni, quando vengono generate eccezioni e quali valori di input significano. Dato un insieme 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 .

È compito tuo fornire sia ai futuri lettori che ai manutentori del tuo codice. Metti tutto il possibile nel codice e il resto nei commenti.

Tieni presente 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 è chiaro dal nome della funzione stesso.

Se, d'altra parte, hai una funzione in cui si deve prima esaminare 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 chiara sia l'implementazione.

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

segui il pubblico

Le molte persone leggono i tuoi javadoc? Se sì, è sensato investire gli sforzi per farlo bene.

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

• Questo è esattamente il caso della documentazione JDK . Indovina Sun / Oracle ha speso molti sforzi su questi e sembra che abbiano un buon rimborso nei documenti API utilizzati molto dalla community.

Ora, è il tuo caso? In caso contrario, pensate due volte se gli sforzi investiti in javadoc sono giustificati.

Come già sottolineato in precedenza, ascolta il pubblico per scoprire come.

• Se senti lamentele attive sulla documentazione insufficiente, considera l'investimento per migliorarlo.
  
  Se, d'altro canto, tutto ciò che senti sono gli sviluppatori che si lamentano delle regole del braindead che li costringono a perdere tempo con la digitazione inutile, beh, allora è molto probabile che i tuoi sforzi di javadoc siano come investire in mutui subprime . Pensa invece a investimenti migliori.

Voglio solo commentare la preoccupazione che i commenti Javadoc possano essere superati. Mentre @JonathanMerlet ha ragione nel dire che Javadoc dovrebbe essere stabile, puoi anche aiutare rivedendo Javadoc e commenti e codice durante la peer review. I commenti corrispondono a ciò che sta facendo il codice? In caso contrario, quale è errato, e insisti allo sviluppatore di risolverlo. Cerca di incoraggiare altri sviluppatori a fare lo stesso. Ciò aiuta a mantenere aggiornati non solo la documentazione esterna (commenti Javadoc), ma anche tutti i normali commenti sul codice. Ciò aiuta gli sviluppatori che arrivano dopo il refactoring a capire il codice in modo più rapido e semplice, e lo rende molto più semplice in futuro.

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