Code Documentation: The Complete Beginner’s Guide

Sei un po ‘ nel tuo primo lavoro di programmazione e le cose stanno diventando più facili. All’inizio, tutto il codice che hai dovuto affrontare potrebbe averti sopraffatto e confuso, ma stai iniziando a capirlo. E ‘ fantastico! Ora ti stai chiedendo come portare il codice che scrivi al livello successivo. Mentre ci sono molte cose da imparare sul tuo stack di programmazione, molte delle quali ti renderanno un programmatore migliore, ce ne sono alcune che ti serviranno indipendentemente dallo stack in cui lavori. Uno di questi è la documentazione del codice.

Molti sviluppatori non scrivono abbastanza documentazione, perché non vedono il valore o perché sentono di non avere tempo. Non è necessario essere uno di quegli sviluppatori. Con un po ‘ di tempo e molta pratica, puoi aggiungere documentazione per il tuo codice che rende la lettura una gioia da usare sia per te che per chiunque altro venga.

Una buona documentazione si presenta in molte forme

Quando la maggior parte degli sviluppatori pensa alla documentazione del codice, pensa ai commenti. I commenti possono essere preziose aggiunte al codice, ma non sono l’unica definizione di documentazione. La documentazione è tutto ciò che scrivi in aggiunta al tuo codice per aiutare qualcun altro a capire come funziona. Potresti non pensarlo in questo modo, ma un buon esempio di documentazione del codice è un file README. Un buon esempio di documentazione di base è l’Express.file js LEGGIMI. Risponde a diverse domande importanti sul framework e ti dice come puoi includerlo nel tuo progetto, come installarlo e come eseguire i test.

Una buona documentazione può venire anche sotto forma di documentazione API. Ancora una volta, Express.js fornisce un ottimo esempio. Questa versione della documentazione è più di una libreria di riferimento per gli sviluppatori che utilizzano il framework. Troverai le risposte alle domande su cosa fanno le singole funzioni e quali parametri diversi significano per tali funzioni. Senza quella documentazione di qualità, Express non avrebbe quasi come molti team che lo utilizzano come fanno.

E, naturalmente, puoi usare anche i commenti in linea per documentare il codice. Questi tipi di commenti di solito non vengono utilizzati per insegnare alle persone al di fuori del proprio team il codice. Invece, sono utili per spiegare cosa sta succedendo in un particolare bit di codice ai tuoi compagni di squadra o al tuo sé futuro.

Perché dovresti documentare il tuo codice

Come notato sopra, molti sviluppatori non capiscono lo scopo della documentazione del codice. Sosterranno che un buon codice dovrebbe essere auto-documentante e che non dovresti aver bisogno di spiegarlo. Queste persone sono, in una parola, sbagliate. La verità è che una buona documentazione è una parte essenziale di qualsiasi base di codice. Perché? Perché le persone non dovrebbero aver bisogno di leggere tutto il tuo codice per capire cosa fa. “Persone” in quella frase precedente può riferirsi a chiunque, incluso il tuo sé futuro.

La verità è che spesso, le “persone” che avranno bisogno di capire il codice dopo che è stato scritto sei tu. Quel po ‘ di logica che sembrava così intelligente quando l’hai scritto sei mesi fa potrebbe essere difficile da capire oggi. Se il tuo codice è ben documentato, non devi perdere tempo a cercare di capire cosa fa. Sarete in grado di trascorrere qualche secondo guardando la descrizione e poi tornare a quello che stai lavorando in questo momento.

Se sei abbastanza fortunato da lavorare su codice utilizzato da dozzine o centinaia di sviluppatori, una buona documentazione è ancora più importante. La vita dei tuoi utenti sarà notevolmente migliorata dal tempo trascorso a scrivere una buona documentazione e ti ringrazieranno per questo. Letteralmente!

La chiave da ricordare è che una buona documentazione consente di risparmiare più tempo del necessario per scriverla. Potrebbe essere il tuo tempo, o potrebbe essere il tempo dei membri del team, o anche persone che non incontrerai mai. A volte, la scrittura della documentazione ti aiuterà anche a riconoscere una parte del tuo codice troppo complicata in modo da poterla semplificare.

Alcuni errori di documentazione comuni

Come sviluppatore junior, dovrai dedicare del tempo a imparare ciò che rende efficace la documentazione. La buona notizia è che si può imparare da persone che sono andati prima di voi in modo da poter evitare errori comuni.

Sotto-Documentazione

Un errore comune che vedo con la documentazione del codice è quello di documentare informazioni già chiaramente visibili. Ad esempio, gli sviluppatori pigri aggiungeranno “documentazione” a una funzione aggiungendo un blocco che fornisce il nome di una funzione, nonché i nomi di ciascun parametro e dei loro singoli tipi. Questo tipo di documentazione è inutile! Ci vogliono pochi secondi perché qualcuno legga il nome della funzione e i parametri necessari. Questa non è documentazione, è solo ripetizione. Invece, la documentazione dovrebbe includere un po ‘ di informazioni su ciò che la funzione fa e come ogni parametro cambia il comportamento della funzione o perché è necessario.

Over-Documentation

Il modello opposto può anche essere un problema serio. Per evitare di scrivere troppo poca documentazione, alcuni sviluppatori amano scrivere la spiegazione per ogni piccolo bit di logica contenuto in una funzione. Documentano meticolosamente ogni logica che è andata a creare la funzione. Nel momento in cui hanno finito, potrebbero aver speso tanto tempo a scrivere la funzione quanto a scrivere la documentazione. Quel che è peggio, la documentazione è spesso difficile da capire e richiede solo il tempo di leggere il codice. Questo tipo di documentazione è anche una perdita di tempo. Invece, una buona documentazione fornisce una spiegazione di base sia del cosa che del perché. Se ci sono parti particolarmente difficili del codice da capire, la documentazione dovrebbe spiegare solo quelle parti.

Basandosi sui test per documentare

Occasionalmente, ti imbatterai in qualcuno che sostiene che la migliore forma di documentazione sono i test unitari. Questo approccio ha una grave lacuna: la lettura dei test unitari è spesso altrettanto difficile da fare quanto la lettura del codice stesso. Qualsiasi sviluppatore che desideri imparare cosa fa il tuo codice avrà un primo grande passo mentre dà la caccia e legge tutti i tuoi test unitari. Molti si arrenderanno prima di raggiungere ciò che si prefiggono di fare. Mentre il test delle unità è una preziosa aggiunta a qualsiasi base di codice, non è un sostituto per una buona documentazione.

Modi per portare la documentazione al livello successivo

Se lavori su una grande base di codice, la documentazione del codice può sembrare scoraggiante, specialmente se non sei stato diligente nel documentare il codice fino a questo punto. Potrebbe sembrare che tu stia cercando di far bollire l’oceano. Se hai una grande base di codice o una in cui sai che una buona documentazione è fondamentale, potresti voler indagare sugli strumenti di documentazione del codice automatizzato. Questi strumenti semplificano drasticamente il processo di scrittura coerente, buona documentazione per un intero team. Uno strumento come GhostDoc esaminerà in modo intelligente il tuo codice e utilizzerà i modelli stabiliti dal tuo team per avviare la documentazione con un paio di tasti premuti. Gli strumenti di documentazione automatizzati rimuovono uno degli altri motivi comuni per opporsi alla scrittura della documentazione: ci vuole troppo tempo.

Una volta che si dispone di una documentazione coerente, altri strumenti consentono di condividere facilmente tale documentazione. Gli strumenti di documentazione automatizzati eliminano il problema dello sviluppo di una buona documentazione per cose come le API pubbliche fornite dal codice.

Inizia oggi

Scrivere una grande documentazione è molto più semplice della scrittura di codice. A differenza del codice, la documentazione non è un’impresa tutto o niente. Inizia con l’obiettivo di scrivere una buona documentazione per una funzione ogni giorno. Questo tipo di pratica costruisce abitudini sane e vedrai il profitto lungo la strada quando passi molto meno tempo a cercare di capire parti della tua base di codice. Nel corso del tempo, inizierà a sentirsi sbagliato quando si scrive codice che non ha una buona documentazione. Inizierai a indicare modi per migliorare la documentazione ai tuoi colleghi durante la revisione del codice. Una piccola abitudine migliorerà il codice della tua squadra per l’intera attività.

Scopri come GhostDoc può aiutarti a semplificare i tuoi commenti XML, produrre e mantenere la documentazione di aiuto di qualità.

Circa l’autore

Eric Boersma

Contribuendo Autore

Eric Boersma è uno sviluppatore di software e sviluppo manager che ha fatto di tutto, dalla sicurezza informatica nel settore farmaceutico per la scrittura di software di intelligenza per il governo americano per la costruzione di internazionale, un team di sviluppo per il non profit. Ama parlare delle cose che ha imparato lungo la strada, e gli piace ascoltare e imparare dagli altri pure.