Dovresti documentare tutto o solo la maggior parte?

Sembra un po 'un argomento controverso documentare tutto, inclusa la sintassi "JavaBean" di getter e setter per i campi: la gente dice che è inutilmente lungo e ripetitivo rompersi DRY (non ripeterti) , che la convenzione di denominazione dovrebbe spiegare tutto , e ingombra il codice / la documentazione. A volte quegli argomenti funzionano. Ma altre volte, si finisce con questo:

Sopra è comune ai progetti open source che seguono coraggiosamente questi principi. Ti resta tutta la documentazione inutile . Questo non spiega nulla di ciò che sta accadendo sotto, i possibili effetti o persino quale sia il valore atteso (potrebbe essere nullo o mai nullo? Non lo so; il Javadoc non me lo dice).

Quindi quando devo documentare? Documento tutto anche se occasionalmente ingombra il codice? O non documento nulla poiché ai miei occhi è "ovvio"?

Documenta tutto ciò che ha senso documentare .

In un mondo ideale, sì, documenteresti tutto. Tuttavia, sulla Terra, abbiamo scadenze, tagli di funzionalità, famiglie e amici da visitare, vacanze da prendere, solo 24 ore al giorno e solo 365 giorni all'anno. Non c'è abbastanza tempo per documentare tutto. Quindi, in modo ottimale, documenta tutto ciò che puoi (non avrai fatto), ma ottieni il massimo dal tuo dollaro:

• Rendere il codice leggibile e le firme dei metodi il più ovvio possibile in modo che la documentazione sia meno probabile .
• Documentare prima le cose più oscure. Aiuta gli altri a documentare i pazzi hack che dovevi fare per far uscire le cose dalla porta.
• Documenta il perché prima del cosa - Non commentare cosa fa qualcosa, ad esempio "Esamina i record dei clienti in cui il saldo è inferiore a zero e il punteggio è inferiore a uno e aggiungili all'elenco Clienti esenti". Documenta il motivo per cui li stai aggiungendo all'elenco in inglese (o nella lingua del tuo team), ad esempio "Poiché questi clienti hanno un saldo negativo e valutazioni basse, ci stanno facendo perdere denaro, quindi escludili dalla possibilità di effettuare il check-out.

Continua a documentare fino a quando non puoi vedere qualcun altro leggerlo senza sentire la necessità di spiegare nulla.

La scorsa settimana è stato pubblicato un ottimo articolo sulla documentazione presso The Daily WTF. Penso che dice tutto, quindi lascerò semplicemente il link:

http://thedailywtf.com/Articles/Documentation-Done-Right.aspx

Fondamentalmente dice che non dovresti documentare qualcosa se non sarà utile (parte della documentazione è appena lasciata a marcire in un cassetto) e documentare la minima quantità di informazioni necessarie per comprendere una certa parte del progetto. Troppa documentazione confonde il lettore.

Dipende molto da quanto sia leggibile il codice per il pubblico che lo legge. Scopri chi è il pubblico per la lettura del tuo codice e chiedi a qualcuno che incontra quel profilo di leggere il tuo codice.

Un altro approccio sarebbe quello di rivedere il proprio codice dopo una settimana e vedere se si capisce ancora cosa si è fatto, in caso contrario, documentarlo e rivedere il codice in circa due settimane.

Anche se apprezzo una documentazione chiara ed estesa, non c'è niente come il codice di auto-documentazione. Quindi, la linea di fondo (per me) è:

Diffidare molto della documentazione (del codice sorgente); prova a renderlo ridondante migliorando il codice, ma non esitare a documentare in modo chiaro e completo quando necessario.

Naturalmente, in determinate circostanze, potrebbe essere richiesta la documentazione per ragioni diverse da "spiegare cosa sta facendo il codice" (ad esempio: una grande squadra, standard organizzativi e così via).

Il mio suggerimento sulla documentazione è che se c'è qualcosa di strano nel codice, questo appartiene a un documento che dovrebbe essere tenuto aggiornato. La fantasia è soggetta a molta interpretazione, nella mia mente è dove qualcosa viene fatto in un modo particolare che può avere effetti collaterali che dovrebbero essere notati, ad esempio qualcosa può essere fatto in modo ricorsivo per garantire che gli oggetti dei nipoti vengano elaborati attraversando un albero di nodi per eseguire alcuni test su tutti i discendenti. Articolare il motivo per cui qualcosa è stato fatto in un modo particolare può essere un buon modo per sapere se ci fosse o meno una buona ragione per usare qualcosa.

In termini semplici, la documentazione è lì per aiutare gli sviluppatori e i manutentori in futuro.

Se ricordi quella semplice massima, allora il livello della documentazione dovrebbe essere auto-definito.

La documentazione, per ragioni di documentazione, è una perdita di tempo ... ma spiegare oggi cosa stai facendo è più utile di qualcuno che deve decodificare il tuo codice tra cinque anni.

Personalmente vado con l'approccio di considerare la documentazione di tutto. Vale a dire, durante la codifica, considero in ogni momento se la documentazione aggiungerebbe valore. Il più delle volte la risposta è sì esattamente per i tipi di vincoli e la conoscenza del dominio menzionati nella domanda originale. Ad esempio nullità, vincoli univoci, interpretazione del campo nel dominio più ampio.

Per evitare duplicazioni, tendo a documentare pesantemente le principali classi API con questo tipo di informazioni. Quindi documenta solo implementazioni e interni in cui vi è un comportamento non ovvio o incoerente. Trovo che funzioni bene in quanto sono gli utenti dell'API che hanno bisogno della maggior quantità di aiuto e documentazione, in genere è lecito ritenere che le persone che modificano l'implementazione conoscano l'API, quindi abbiano questa conoscenza.

Tendo anche a documentare solo i getter. Non duplico documentazione su setter, definizioni di campo e parametri del costruttore. Documento solo comportamenti non ovvi come i valori predefiniti in questi luoghi. Qualsiasi comportamento che può essere dedotto dalla documentazione getter non è documentato. Ad esempio, se il getter è documentato come null senza ritorno, generalmente non documento che non è possibile passare null al setter, a meno che non ci sia un valore predefinito.

Ad alcune persone piace contrassegnare questo atto di "considerazione della documentazione" aggiungendo commenti vuoti in cui hanno considerato la documentazione ma l'hanno trovata superflua. Non mi piace questa pratica in quanto ingombra il codice e si mette in mezzo.