Cos'è la documentazione del codice?

La documentazione del codice funge da mappa per coloro che interagiscono con una base di codice, aiutandoli a capire cosa fa ogni pezzo di codice, come funziona, come usarlo e come tutti i pezzi di codice si incastrano. Documentare il codice aiuta i team di sviluppo a mantenere meglio il codice sorgente, guidando anche altri stakeholder che potrebbero aver bisogno di comprendere e lavorare con il codice, come analisti di cybersecurity , data scientist, ingegneri DevOps, product e project manager, ingegneri QA e technical writer.

La documentazione come codice, o "docs as code", tratta la documentazione come se fosse codice software. Questo approccio gestisce la documentazione utilizzando gli stessi strumenti del codice sorgente, inclusi sistemi di controllo versione per rivedere e monitorare le modifiche, test automatizzati per identificare problemi di formattazione e stile, e integrazione continua/consegna continua (CI/CD) per l'aggiornamento e la distribuzione della documentazione.

Mentre la documentazione del codice comprende la pratica più ampia di documentare il codice, docs as code è una strategia specifica e un approccio più tecnico alla scrittura della documentazione.

La struttura della documentazione del codice dipenderà da chi è il pubblico e da come verrà utilizzato. Ecco alcuni tipi comuni di documentazione:

• Documentazione di basso livello
  
  
• Documentazione di alto livello
  
  
• Documentazione interna
  
  
• Documentazione esterna

La documentazione di basso livello si riferisce in genere ai commenti inline all'interno del codice. Essendo uno dei metodi più basilari per scrivere la documentazione, queste annotazioni spiegano particolari righe o blocchi di codice.

Le stringhe di documentazione o docstring sono un'altra tecnica di documentazione di basso livello. Compaiono prima della definizione di una classe, di una funzione, di un metodo o di un modulo. Le docstring hanno un formato strutturato che dichiara scopo, esempi di utilizzo, funzionalità, parametri e valori restituiti.

I commenti inline sono più adatti a specificare la logica quando non può essere ricavata esaminando il codice stesso o per il codice basato su algoritmi più complessi. Nel frattempo, i docstring possono essere estratti per la documentazione dell'interfaccia di programmazione applicativa (API) e fornire supporto contestuale all'interno degli ambienti di sviluppo integrati (IDE).

A differenza della documentazione di basso livello, che descrive porzioni di codice come entità individuali, la documentazione di alto livello include dettagli sul loro ruolo nel workflow architetturale più ampio. Questo tipo di documentazione software comprende diagrammi di flusso e diagrammi UML (Unified Modeling Language) che illustrano l'architettura del codice, documenti di progettazione che delineano la logica aziendale e il modo in cui il codice si allinea ai requisiti del prodotto e alle specifiche della struttura delle basi di codice o dei repository di codice.

Questa documentazione tecnica è destinata all'uso interno di un'azienda. Gli esempi includono convenzioni e standard di codifica e documenti di processo su come i team creano software. Anche le guide per la configurazione degli ambienti di sviluppo rientrano nella documentazione interna.

Questa documentazione rivolta all'utente è orientata agli sviluppatori e ad altri utenti esterni all'azienda. Ad esempio, la documentazione API illustra le classi, le funzioni, i metodi e i moduli disponibili delle API pubbliche di un progetto software. La documentazione esterna può anche essere costituita da file di configurazione, note di integrazione e un file README.

Il file README è scritto in Markdown, un linguaggio di markup leggero per la formattazione di testo semplice. Contiene informazioni sulle funzionalità del progetto, dipendenze, istruzioni di installazione, comandi dell'interfaccia da riga di comando (CLI) e opzioni per ottenere aiuto e supporto. I progetti open source includono anche dettagli sulle licenze e linee guida per i contributori che desiderano inviare pull request per integrare correzioni di bug o modifiche al codice nel ramo principale del repository.

Scrivere codice in modo pulito e chiaro può essere una forma di documentazione a sé stante. Tuttavia, una buona documentazione rimane essenziale e offre questi vantaggi:

• Migliora la collaborazione

• Migliora la manutenibilità

• Accelera lo sviluppo del software

• Semplifica l'onboarding

Un codice ben documentato favorisce una migliore collaborazione e comunicazione all'interno dei team di sviluppo. I membri possono utilizzare la documentazione del codice come linguaggio condiviso per condurre recensioni del codice, discutere delle modifiche al codice e prendere decisioni in team.

La documentazione facilita il refactoring del codice, la manutenzione e l'ottimizzazione delle prestazioni. Durante il debug, gli sviluppatori possono utilizzare la documentazione del codice come punto di riferimento per trovare errori di codifica e individuarne la causa principale.

Una buona documentazione apre la strada a uno sviluppo rapido, risparmiando tempo nel capire la funzionalità del codice e riportando l'attenzione all'applicazione degli aggiornamenti appropriati. Aiuta anche a monitorare i cambiamenti, assicurando che i team possano tenere il passo con una base di codice in continua evoluzione.

La documentazione del codice aiuta i nuovi membri del team ad apprendere il funzionamento interno di una base di codice. Possono familiarizzare più rapidamente con la progettazione e la struttura del codice, consentendo loro di contribuire rapidamente al progetto.

Codice e documentazione lavorano di pari passo, quindi devono evolversi insieme. E alcune linee guida per la scrittura del codice si applicano anche alla scrittura della documentazione. Ecco alcuni consigli che possono essere utili:

• Stabilire standard di documentazione del codice

• Integrare la documentazione con la codifica

• Chiarezza e concisione sono fondamentali

• Documentare le decisioni di codifica 

• Aggiornare continuamente

Come per le convenzioni di codifica, anche per la documentazione del codice è necessario rispettare degli standard. Questi standard includono una formattazione coerente, come il rientro, le interruzioni di riga e la spaziatura per la documentazione di basso livello. Nel frattempo, i modelli e gli strumenti di documentazione del codice possono essere d'aiuto per lo stile e la struttura della documentazione delle API e di altra documentazione di alto livello ed esterna.

Ciò potrebbe comportare l'aggiunta di docstrings al completamento di una funzione o l'inserimento di commenti inline durante l'implementazione di algoritmi o logiche complesse. Redigere la documentazione durante la programmazione può aiutare gli sviluppatori ad articolare il proprio processo di pensiero e il processo decisionale, assicurando che i dettagli cruciali non vadano persi lungo il percorso. Potrebbe richiedere un po' di tempo in più all'inizio, ma può diventare una parte naturale del processo di codifica e può accelerare il debugging, l'ottimizzazione e il refactoring in futuro.

Un'eccessiva documentazione può ostacolare la leggibilità del codice. Gli sviluppatori devono dare priorità alla scrittura di codice pulito e chiaro, per poi aggiungere la documentazione necessaria che si integri perfettamente con tale codice.

In termini di concisione, trovare il giusto equilibrio è fondamentale. Ad esempio, frammenti di codice brevi e semplici potrebbero non richiedere alcuna documentazione. D'altra parte, algoritmi più sofisticati richiedono documentazione che spieghi la logica sottostante in modo che sviluppatori con diversi livelli di esperienza possano comprendere.

Ciò include scelte di progettazione, architettura, logica e algoritmi. Documentare queste decisioni di codifica, sia attraverso un documento interno di alto livello sia tramite una base di conoscenza condivisa, offre un contesto per eventuali cambiamenti da apportare in futuro.

I team di sviluppo devono condurre revisioni e aggiornamenti periodici della documentazione del codice per assicurarsi che sia accurata, completa e pertinente, che rifletta lo stato attuale del software. Incorporare la documentazione nel processo di revisione del codice può aiutare con aggiornamenti regolari.

La maggior parte degli IDE dispone di estensioni o plugin per la generazione della documentazione del codice, ma anche altri framework e strumenti possono contribuire ad automatizzare il processo. Ecco alcuni dei generatori di documentazione più comuni:

• Doxygen

• GitBook

• Javadoc

• JSDoc

• Sphinx

Doxygen supporta diversi linguaggi di programmazione, come C, C++, Java, PHP e Python. Permette il rendering markdown e può produrre documentazione in formati HTML, PDF e XML. Doxygen può essere personalizzato tramite un file di configurazione e offre la possibilità di generare diagrammi che rappresentano gerarchie visive e correlazioni tra classi e funzioni.

GitBook offre un'interfaccia utente per scrivere e pubblicare documentazione come sito web, che può rendere più efficiente la creazione sia di documentazione interna che esterna. La piattaforma offre anche la sincronizzazione con i repository GitHub o GitLab.

Lo strumento Javadoc analizza i commenti della documentazione all'interno del codice sorgente Java per generare documentazione API in formato HTML. Può documentare classi, costruttori, campi, interfacce e metodi.

Simile a Javadoc, JSDoc genera documentazione API per progetti JavaScript. La sua comunità open-source ha sviluppato modelli e strumenti per personalizzare la documentazione.

Sphinx è principalmente costruito per Python ma si estende anche ad altri linguaggi di programmazione. Supporta il markdown e un proprio linguaggio di markup chiamato reStructuredText. Sphinx può creare documentazione in vari formati di output e dispone di riferimenti incrociati per collegarsi ad altri elementi di codice.

I generatori di documentazione si limitano alle annotazioni che incontrano nel codice sorgente. L'AI generativa porta la documentazione oltre, analizzando un specifico frammento di codice e aggiungendo commenti che ne descrivono lo scopo e la funzione. Molti modelli linguistici di grandi dimensioni (LLM) per il codice hanno funzionalità integrate per la generazione di documentazione.

Ad esempio, IBM Bob può generare righe di commento per un singolo metodo o per tutti i metodi all'interno di una classe. Tra gli altri strumenti simili si annoverano GitHub Copilot, JetBrains AI Assistant, Mintlify e Tabnine.

Come con qualsiasi sistema di intelligenza artificiale, gli sviluppatori devono comunque esaminare gli output degli strumenti di documentazione del codice basati su AI per verificarne la completezza e l'accuratezza.