Dovresti documentare tutto o solo la maggior parte?

Documenta tutto che ha senso documentare .

In un mondo ideale, sì, dovresti documentare tutto. Tuttavia, sulla Terra, abbiamo scadenze, tagli di funzioni, famiglie e amici da visitare, vacanze da fare, 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 finito), ma ottieni il massimo dal tuo investimento:

• Rendi il codice leggibile e le firme dei metodi il più ovvio possibile in modo che la documentazione sia meno probabile necessaria.
• Documentare prima le cose più oscure. Aiuta gli altri documentando gli hack impazziti che devi fare per far uscire le cose.
• Documenta perché prima di ciò che - Non commentare cosa fa qualcosa, ad esempio "Iterate sui record del cliente in cui il saldo è inferiore a zero e la valutazione è inferiore a uno e aggiungili ai clienti esenti elenco". Documenta perché li stai aggiungendo alla lista in inglese semplice (o nella lingua della tua squadra), come "Poiché questi clienti hanno un saldo negativo e valutazioni basse, ci stanno facendo perdere denaro, quindi li escludiamo da poter controllare.

Continua a documentare finché non riesci a guardare qualcun altro a leggerlo senza sentire la necessità di spiegare nulla.

La settimana scorsa c'era un grande articolo riguardante la documentazione di The Daily WTF. Penso che dica tutto, quindi lascerò il link:

link

Sostanzialmente si dice che non si dovrebbe documentare qualcosa se non sarà utile (alcuni documenti vengono lasciati marcire in un cassetto) e documentare la minima quantità di informazioni necessarie per capire una certa parte del progetto . Troppa documentazione confonde il lettore.

Dipende davvero da quanto leggibile il codice è per il pubblico che lo legge. Scopri chi è il pubblico che legge il tuo codice e chiedi a qualcuno che soddisfa quel profilo di leggere il tuo codice.

Un altro approccio sarebbe quello di rivedere il tuo codice dopo una settimana e vedere se riesci ancora a capire cosa hai fatto, se non lo hai fatto, documentalo e rivedi il codice tra due settimane circa.

Pur apprezzando una documentazione chiara ed estesa, non c'è nulla come il codice di autocertificazione. Quindi, la linea di fondo (per me) è:

Diffidate 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, la documentazione può essere richiesta per ragioni diverse da "spiegare cosa sta facendo il codice" (ad esempio: grande base di lavoro, standard di organizzazione e così via).

Il mio suggerimento sulla documentazione è che se c'è qualcosa di elaborato nel codice, questo appartiene a un documento che dovrebbe essere tenuto aggiornato. Immaginare di essere soggetto a molte interpretazioni, nella mia mente è dove qualcosa viene fatto in un modo particolare che può avere effetti collaterali che dovrebbero essere notati, per es. qualcosa può essere fatto in modo ricorsivo per garantire che gli oggetti grandchild vengano elaborati passando attraverso 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 ora e i manutentori in futuro.

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

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

Personalmente vado con l'approccio di prendere in considerazione la documentazione di tutto. Cioè durante la codifica, considero in ogni punto se la documentazione potrebbe aggiungere valore. La maggior parte delle volte la risposta è sì per esattamente i tipi di vincoli e le conoscenze di dominio menzionate nella domanda originale. Per esempio. nullità, vincoli univoci, interpretazione del campo nel dominio più ampio.

Per evitare la duplicazione, tendo a documentare pesantemente le principali classi API con questo tipo di informazioni. Quindi solo implementazioni documentali e internals dove c'è un comportamento non ovvio o incoerente. Trovo che questo funzioni bene poiché sono gli utenti dell'API che hanno bisogno del maggior aiuto e della documentazione, in genere è sicuro che le persone che modificano l'implementazione conoscano l'API, quindi hanno questa conoscenza.

Tendo anche a documentare solo i getter. Non duplo la documentazione su setter, definizioni dei campi e parametri del costruttore. Ho solo documentato comportamenti non ovvi come i default in questi posti. Qualsiasi comportamento che può essere dedotto dalla documentazione getter non è documentato. Ad esempio, se il getter è documentato come null-return, generalmente non documento che non puoi passare null al setter, a meno che non ci sia un default.

Ad alcune persone piace contrassegnare questo atto di "considerare la documentazione" aggiungendo commenti vuoti dove hanno preso in considerazione la documentazione ma non lo hanno trovato necessario. Non mi piace questa pratica in quanto limita il codice e si intromette.