La documentazione del codice è un processo con cui un programmatore documenta il codice. È un termine ben noto tra gli ingegneri. Se non lo fanno, questo porta ad una scarsa leggibilità del codice e ad una difficile manutenzione per gli altri membri del team.
La documentazione del codice è diversa dalla documentazione del progetto in quanto mira principalmente a come funziona il sistema, ma questi due processi hanno qualcosa in comune – i requisiti dell’uso di uno strumento professionale. In questo articolo, faccio una panoramica di alcuni strumenti popolari per la creazione di documentazione del codice.
LaTex
LaTeX è un sistema di preparazione di documenti per la composizione di alta qualità. È più spesso usato per documenti tecnici o scientifici medio-grandi, ma può essere usato per quasi ogni forma di pubblicazione.
LaTeX non è un elaboratore di testi! Al contrario, LaTeX incoraggia gli autori a non preoccuparsi troppo dell’aspetto dei loro documenti ma a concentrarsi sull’ottenere il giusto contenuto.
LaTeX è un sistema di composizione tipografica di alta qualità; include caratteristiche progettate per la produzione di documentazione tecnica e scientifica. LaTeX è lo standard de facto per la comunicazione e la pubblicazione di documenti scientifici. LaTeX è disponibile come software libero.
Non si deve pagare per usare LaTeX, cioè, non ci sono costi di licenza, ecc.
Pandoc
Pandoc comprende un certo numero di utili estensioni della sintassi di markdown, compresi i metadati del documento (titolo, autore, data); note a piè di pagina; tabelle; elenchi di definizioni; apici e pedici; strikeout; elenchi ordinati migliorati (il numero iniziale e lo stile di numerazione sono significativi); elenchi di esempi in esecuzione; blocchi di codice delimitati con evidenziazione della sintassi; virgolette intelligenti, trattini ed ellissi; markdown dentro blocchi HTML; e LaTeX in linea. Se si desidera una stretta compatibilità con markdown, tutte queste estensioni possono essere disattivate.
Ci sono molti modi per personalizzare Pandoc in base alle proprie esigenze, compreso un sistema di template e un potente sistema per scrivere filtri.
Pandoc include una libreria Haskell e un programma a riga di comando autonomo. La libreria include moduli separati per ogni formato di input e di output, così l’aggiunta di un nuovo formato di input o di output richiede solo l’aggiunta di un nuovo modulo.
Pandoc è software libero, rilasciato sotto GPL.
Markdown
Markdown è uno strumento di conversione testo-HTML per scrittori web. Markdown ti permette di scrivere usando un formato di testo semplice facile da leggere e da scrivere, per poi convertirlo in XHTML (o HTML) strutturalmente valido.
L’obiettivo principale della sintassi di formattazione di Markdown è di renderlo il più leggibile possibile. L’idea è che un documento formattato in Markdown dovrebbe essere pubblicabile così com’è, come semplice testo, senza sembrare che sia stato marcato con tag o istruzioni di formattazione. Mentre la sintassi di Markdown è stata influenzata da diversi filtri text-to-HTML esistenti, la singola più grande fonte di ispirazione per la sintassi di Markdown è il formato delle email di testo semplice.
LiveEdu
LiveEdu ti permette di trasmettere la tua documentazione del codice e creare “Video documentazione del codice.”
Education Ecosystem è un ecosistema di apprendimento decentralizzato che insegna a professionisti e studenti universitari come costruire prodotti reali. Si può descrivere il nostro prodotto come un ibrido tra Pluralsight e Twitch. Stiamo costruendo il più grande ecosistema di apprendimento al mondo per i futuri argomenti tecnologici come l’intelligenza artificiale, la sicurezza informatica, lo sviluppo di giochi, la scienza dei dati, le criptovalute e la programmazione. Education Ecosystem è basato su video e ogni progetto contiene video, un profilo di progetto strutturato, repo di progetto e risorse scaricabili. Gli utenti possono clonare le risorse del progetto da Education Ecosystem Git ed eseguire le applicazioni sulla loro macchina locale.
Sphinx
Sphinx è uno strumento che rende facile creare documentazione intelligente e bella, scritto da Georg Brandl e con licenza BSD.
E’ stato originariamente creato per la documentazione Python, e ha eccellenti strutture per la documentazione di progetti software in una serie di linguaggi. Ecco alcune caratteristiche:
- Formati di output: HTML (incluso Windows HTML Help), LaTeX (per versioni PDF stampabili), ePub, Texinfo, pagine di manuale, testo semplice.
- Ampi riferimenti incrociati: markup semantico e collegamenti automatici per funzioni, classi, citazioni, termini del glossario e informazioni simili.
- Struttura gerarchica: facile definizione di un albero del documento, con collegamenti automatici a fratelli, genitori e figli.