La documentazione del software (e dei progetti in genere)

Qualche puntualizzazione

Documentazione della documentazione Questo piccolo testo illustra le mie esperienze sulla scrittura della documentazione, se lo trovate utile significa che è una documentazione scritta bene. Di fatto è una meta-documentazione
Legge del minimo, o legge di Liebig la legge del minimo recita: "In agronomia la crescita è controllata non dall'ammontare totale delle risorse, ma dalla disponibilità della più scarsa." https://it.wikipedia.org/wiki/Legge_di_Liebig Si può applicare anche ad altri contesti, ad esempio alla produzione industriale, ma anche alla produzione del software e quindi ritengo che si possa dire: Un prodotto software vale quanto la sua documentazione
Tipi di documentazione Ritengo che si possano individuare tre tipi di documentazione:
1 documentazione delle procedure
2 documentazione per l'utente
3 linee guida ed appunti per i programmatori
Questo documento Se cercate su un motore di ricerca "documentazione del software" oppure "software documentation" escono moltissime pagine che spiegano anche in modo rigoroso questo argomento. Io non l'ho fatto perché mi voglio basare solo sulle mie esperienze personali, forse lo farò dopo aver finito di scrivere. La speranza è quella di non sbagliare troppo, e magari proporre qualche spunto originale. Come linguaggio di riferimento per gli esempi di codice ho usato Python
Gli errori Molte delle note che seguono sono basate su errori che ho fatto, alcuni dei software che scrivo li sto mantenedo da molti anni e spesso mi capita di trovare stili di programmazione e documentazione che ora farei in modo diverso. Purtroppo esistono anche strumenti di cui riconosco l'utilità ma che non sono in grado al momento di metterle in pratica.

Fai parte di un team o sei un programmatore individuale?

Non importa, questa distinzione non esiste. Se scrivete software che viene modificato anche da altre persone dovete fare in modo che essi siano in grado di capire immediatamente le funzionalità e di fare modificare senza introdurre errori logici.

Il fatto è che gli altri a cui è destinata la documentazione siete anche voi, anzi, spesso siete proprio voi. Vi posso assicurare che con il passare del tempo vi dimenticherete di molte cose e se non le avrete scritte perderete molto tempo per ricordare o per ricostruire le funzionalità.

La documentazione inserita nel codice.

La prima forma di documentazione del codice è la chiarezza e l'ordine con cui è scritto.

Quasi tutti i linguaggi più diffusi hanno linee guida sullo stile di scrittura, alcune sono ufficiali ed altre proposte da utenti. Ad esempio:
https://www.python.org/dev/peps/pep-0008/
https://en.wikibooks.org/wiki/PHP_Programming/Commenting_and_Style
https://google.github.io/styleguide/javaguide.html
https://www.w3schools.com/js/js_conventions.asp

Se pensate di distribuire il vostro codice in modo open, consigliamo di attenersi alle linee guida ufficiali, ad esempio per il codice Python consiglimo di adeguarsi al PEP 8, amichevolmente chiamato Pepotto ;-)

Per il codice interno si può decidere un proprio stile se non siete d'accordo con le linee guida ufficiali. Ad esempio in PHP alcune guide potrebbero suggerire di scrivere le funzioni in questa forma:

function min($a, $b)
{
        if($a < $b)
        {
                return $a;
        } 
        else
        {
                return $b;
        }
}

Io preferisco scrivere:

function min($a, $b) {
    if($a < $b) {
        return $a;
    } else {
        return $b;
    }
}

Che trovo più compatta e leggibile. Non mi spingerei invece fino a scrivere:

function min($a, $b) {
    if($a < $b) return $a else return $b;
}

Anche se potrebbe aver senso scrivere:

function min($a, $b) {
    return ($a < $b) ? $a : $b;
}

In questo ultimo esempio si utilizza una caratteristica sintassi del linguaggio e non delle scorciatoie descrittive.

Se si decide di utilizzare uno stile proprio, la cosa importante è che tutto il progetto segua lo stesso stile.

Le linee guida, di solito si dilungano anche sul numero di righe vuote tra una funzione e l'altra, sui nomi delle variabili, sul uso delle parentesi e molto altro, ma io non ne parlerò perché non è lo scopo di questo documento.

Anche il modo di scrivere il codice influisce sulla leggibilità

Alle volte può capitare che l'ottimizzazione del codice penalizzi di molto la leggibilità. In questi casi bisogna fare una scelta, ad esempio se una porzione di codice non è particolarmente critica, si può decidere di scrivere codice un po' meno efficiente, ma molto più leggibile. Ad esempio in questi giorni mi è capitato di vedere codice scritto in questo modo:

name = variant and "%s (%s)" % (product_name, variant) or product_name

Che si può scrivere anche così:

name = "%s (%s)" % (product_name, variant) if variant else product_name

O addirittura:

name = product_name
if variant:
    name = "%s (%s)" % (product_name, variant)

Io delle tre scelgo la seconda perché è leggibile senza essere pedante. Naturalmente questo tipo di giudizio è soggettivo e può cambiare in base al contesto, ad esempio se la logica è semplice, si può scegliere una forma più contratta, ed invece se la complessità sale si sceglie di rendere più leggibili i punti critici.

I commenti al codice

Possiamo distinguere 3 tipi di commenti, i commenti di modulo, i commenti delle funzioni e dei metodi ed i commenti di riga.

I commenti di modulo, di solito vengono scritti all'inizio del file sorgente e servono per documentare la funzionalità complessiva del insieme di funzioni e classi che contiene.

Il punto più importante in cui si scrive la documentazione è nella definizione dei metodi e delle funzioni. La maggior parte dei linguaggi consiglia di scrivere i commenti appena sopra, ad esempio in Java:

 /**
  * Allocates a new string that contains the sequence of characters
  * currently contained in the string buffer argument. The contents of the
  * string buffer are copied; subsequent modification of the string buffer
  * does not affect the newly created string.
  *
  * @param  buffer
  *         A {@code StringBuffer}
  */
 public String(StringBuffer buffer) {
     String result = buffer.toString();
     this.value = result.value;
     this.count = result.count;
     this.offset = result.offset;
 }

Alcuni invece mettono la documentazione appena sotto la dichiarazione della funzione, ad esempio in Python:

def strip(s, chars=None):
    """strip(s [,chars]) -> string

    Return a copy of the string s with leading and trailing
    whitespace removed.
    If chars is given and not None, remove characters in chars instead.
    If chars is unicode, S will be converted to unicode before stripping.

    """
    return s.strip(chars)

In questo caso esiste un motivo ben preciso, infatti Python utilizzando questa forma riconosce automaticamente la documentazione della funzione. Provate a lanciare python2 e scrivere:

>>> import string
>>> print(string.strip.__doc__)

Le librerie ufficiali dei linguaggi di solito scrivono la documentazione utilizzando alcune convenzioni ben precise che servono per produrre la documentazione automatica usando tools appositi, ad esempio tutta la documentazione di Python è ricavata dai commenti inseriti nel sorgente: https://docs.python.org/2.7/library/string.html?highlight=strip#string.strip

La stessa cosa avviene anche in Java e probabilmente in altri linguaggi. Ad onor del vero si deve dire che Java è stato il primo linguaggio che ha adottato questa tecnica che evidentemente è stata apprezzata anche da altri.

Un altra cosa che si può notare è che spesso nelle librerie ufficiali il numero di righe impiegate per la documentazione è molto maggiore di quello utilizzato per il codice stesso, e questo la dice lunga sulla importanza che viene posta sulla documentazione.

Nella documentazione delle proprie applicazioni potrebbe essere eccessivo applicare le regole delle librerie standard perché il campo di utilizzo è più limitato ed anche la platea degli utilizzatori delle funzioni è più circoscritto.

Oltre alla documentazione in intestazione, spesso è necessario inserire commenti anche lungo il codice, ma di solito questi commenti occupano una o due righe al massimo. Se un pezzo di codice richiede un commento di più righe, ad esempio cinque o sei, vale la pena di chiedersi se è il caso di spezzare la funzione in due parti e mettere il codice in oggetto in una funzione separata.

Che cosa scrivere nei commenti

La prima cosa che si deve scrivere nei commenti di testata di funzione o dei moduli è quello che fa. Ma non basta, a volte è anche importante scrivere il motivo per cui è stata scritta e anche il confronto con funzioni simili.

Spesso una funzione viene scritta per rispondere ad una esigenza specifica che si è presentata in un determinato punto dell'applicazione, in questi casi è bene citare la funzionalità che ne ha richiesto la scrittura.

La documenetazione serve non solo per poter utilizzare una funzione nel modo corretto, ma anche per modificare la funzione in caso di modifica dei requisiti. Più la documentazione è chiara e più è facile fare modifiche senza introdurre errori e se si sa chi la utilizza è certramente più facile verificare che il comportamente rimanga consistente.

Quando si modifica una funzione, è bene scrivere a parte quali modifiche sono state fatte e se è una modifica consistente anche la data in cui è stata fatta. In questo modo sarà più facile capire qual'era il comportamento precedente e conservare il comportamento degli utilizzatori precedenti.

Anche se si utilizzano sistemi di versione del codice tipo git, ritengo che la documentazione delle differenze sia comunque un modo immediato per facilitare l'utilizzo delle funzioni.

Dal mio punto di vista fa parte della documentazione anche la stesura delle procedure di test di cui parleremo un po' più avanti.

Io di solito quando scrivo una funzione o una classe di utilizzo abbastanza generico mi comporto così. Prima scrivo la funzione, poi scrivo alcune funzioni di test ed infine scrivo la documentazione. Ovviamente queste fasi non sono proprio separate infatti di solito si portano avanti tutte tre contemporaneamente, ma comunque è una indicazione di priorità.

Alcune teorie di "Extreme Programming" e "Agile programming", teorizzano tra le altre cose che si dovrebbe partire dai requisiti e quindi prima scrivere i test ed in seguito scrivere le funzioni che li soddisfano. Può darsi se sia un approccio migliore, ma può essere difficile da calare in realtà esistenti come ad esempio quella in cui mi trovo io.

Alle volte capita di scrivere codice sotto la pressione della fretta, in questi casi viene la tentazione di rimandare la stesura della documentazione. Consiglio vivamente di evitare di cedere, la mia esperienza mi dice che anche dopo poche ore è facile dimenticare qualche passaggio logico e quindi ritardare la documentazione spesso implica la stesura di una documentazione carente, senza contare che se si opera sotto il condizionamento della fretta, può capitare di "dimenticare" del tutto di fare la documentazione. Bisogna essere rigorosi in questo.

Questo ha a che fare con i meccanismi della memoria a breve termine e la memoria a lungo termine. In un famoso studio, alcuni psicologi avevano notato che i camerieri dei bar ricordavano facilmente le portate che avevano fatto ai tavoli che dovevano ancora pagare, ma dopo un po' che il conto era stato saldato, dimenticavano completamente le portate e dimostravano che per portare un ricordo dalla memoria a breve alla memoria a lungo era necessario un meccanismo che fissasse la memoria, ad esempio se accadeva un incidente in un determinato momento era facile che ricordassero le portate dei tavoli sospesi in quel momento.

Il succo del discorso è che portare i ricordi dalla memoria a breve alla memoria a lungo costa fatica, per cui è meglio scrivere subito per evitare la fatica di ricordare. Verba volant, scripta manent

Regole sparse

La documentazione di modulo e di funzione descrivono le funzionalità, la documentazione di riga migliora la leggibilità del testo:

def XML_header(node):
    
    # informazioni del mittente
    soggetto = node.addNode("Mittente")
    soggetto.addElement("Nome", "Rossi SPA")
    soggetto.addElement("PartitaIva", "012345670123")
    
    # informazioni del destinatario
    soggetto = node.addNode("Destinatario")
    soggetto.addElement("Nome", "Verdi SRL")
    soggetto.addElement("PartitaIva", "098765430321")

Non documentate l'ovvio:

# questa riga somma la variabile c alla variabile b e mette il risultato in a
a = b + c

I nomi delle variabili dipendono dallo scope di utilizzo:

# le variabili globali dovrebbero essere molto descrittive
colore_dello_sfondo = #f0ffff

# ma esistono eccezioni per le variabili usate molto ad esempio i singleton
# che sono oggetti che contengono i dati complessivi dell'applicazione
my_app = SingletonApp()

# alcuni linguaggi consigliano di nominare le costanti con caratteri maiuscoli
PI = 3.1428

# le variabili utilizzate in un contestro breve possono essere corte
sum_my_list = 0
for i in list:
    sum_my_list += i
    print(sum_my_list)
print("The total sum is %d" %sum_my_list)

Esistono diversi stili nella dichiarazione delle variabili, eccone alcuni:

nomi_con_underscore = None
camelCase = None # le gobbe del cammello
UpperCaseCamel = None # come il camel case ma con la prima maiuscola
szName = "Name" # notazione ungherese, inventata da Microsoft, i primi caratteri indicano il tipo di dato.

Di solito le Classi iniziano con la maiuscola e istanze con la minuscola

class ElectronicInvoice():
    pass
    
my_invoice = ElectronicInvoice()

I test come documentazione

Se lo scopo della documentazione è quello facilitare l'uso corretto delle funzioni e delle classi, il miglior modo per documentare è sicuramente quello di scrivere funzioni che usano il codice da testare.

Lo scopo dei test in realtà è quello di fare in modo che in caso di modifiche il codice continui a funzionare come previsto e per questo motivo dovrebbero controllare tutti i possibili usi del codice da testare, ma come effetto collaterale si ottiene che illustrano il modo in cui si dovrebbe utilizzare il codice.

I test possono essere di vari tipi, i più importanti sono sicuramente i test automatici, che ad esempio in Python si realizzano utilizzando la libreria unittest.

https://docs.python.org/3.7/library/unittest.html https://pythontesting.net/framework/unittest/unittest-introduction/

import unittest

class mytest(unittest.TestCase):
    def test_div(self):
        self.failUnless(5/5 == 1)

if __name__ == '__main__':
    unittest.main()

nei test automatici si fanno delle asserzioni e per ogni asserzione il risultato può essere quello atteso oppure no, una suite di test dovrebbe testare tutte le possibili combinazioni e per ogni asserzione il programma di test ci avvisa se il test ha avuto successo.

In fase di sviluppo può succedere che modificando una funzione si modifichi un comportamento sottoposto a test e se il test fallisce è facile scoprire in che punto si verifica il problema.

In alcuni casi però è difficile fare i test automatici perché i risultati dipendono da interazioni con gli utenti oppure da complessi stati esterni come ad esempio contenuti di database.

Nel caso delle interazioni con gli utenti esistono software specifici che simulano le azioni degli utenti, ad esempio per testare pagine web ci sono utility che simulano il click del mouse nei pulsanti, l'inserimento di testo e così via.

Per le interazioni con complessi stati di database, si potrebbero costruire dei speciali programmi che forniscono le varie condizioni di dato chiamati mock-up.

Negli ultimi due casi però l'azione di test diventa faticosa e talvolta il costo per mettere a punto il test supera il beneficio.

Linee guida ed appunti

Oltre alla documentazione in senso stretto del codice con i commenti, lo stile ed i test, in fase di sviluppo spesso si utilizzano documenti estemporanei.

A me ad esempio capita spesso di andare da clienti e di prendere appunti su carta delle modifiche da fare, poi quando rientro scrivo dei semplici files di testo nei quali approfondisco l'analisi, poi incomincio a scrivere il codice ed in seguito può capitare di modificare gli appunti aggiungendo note che possono anche contraddire le asserzioni iniziali.

I testi degli appunti spesso vengono accompagnati anche da files di varia natura, ad esempio pdf con documentazioni, oppure fogli di calcolo con dati di esempio.

Questa metodologia di lavoro viene usata anche quando decido di introdurre nuove funzionalità ai programmi. A volte gli appunti non danno luogo alla scrittura immediata di codice, infatti non è detto che le idee vengano messe in pratica per vari motivi, ad esempio perché risultano troppo complesse da implementare, oppure perché i benefici non sono sufficienti oppure semplicemente si fissano alcune idee che sono solo ipotesi di lavoro.

Di fatto il concetto in questo caso è quello di mettere a frutto idee che altrimenti sarebbero volatili e se non vengono fissate, semplicemente vanno perse. Non è detto che in seguito queste note vengano rilette, e se lo sono, non è detto che si capisca e si ricordi esattamente il flusso logico che le ha generate.

Quindi la prima abilità richiesta quando si scrivono appunti è quella di spiegare nel modo più chiaro il proprio pensiero e se in seguito si cambia idea, invece di cancellare il pensiero originale si integra con le nuove idee. Purtroppo non è facile fissare bene le idee, io molto spesso mi accorgo che il più delle volte quando rileggo i testi dopo tempo, faccio fatica a ricordare tutti i contesti, ecco perché mi sforzo sempre di più a scrivere in modo chiaro.

Alla fine se gli appunti danno luogo alla scrittura del codice non è raro che il testo viene ricopiato nel codice sorgente in qui viene applicato, oppure che nel codice vengano inseriri i riferimenti su come trovare i documenti di esempio o anche il contesto in cui è stata originata la richiesta.

Nella gestione degli appunti, a volte il problema più grosso è anche ricordare dove sono stati memorizzati, io cerco di tenerli ordinati in cartelle apposite, ma nel corso del tempo può capitare di cambiare metodologia di archiviazione, oppure ci possono essere appunti che trattano più argomenti ed allora l'archiviazione potrebbe risiedere in una posizione diversa rispetto all'argomento corrente.

Per mettere ordine agli appunti, ognuno a proprio modo dovrebbe utilizzare alcuni dei molti strumenti disponibili di cui parleremo un po' più avanti.

Mi rendo conto che non è una grade scoperta dire che se si fanno bene gli appunti si organizza meglio il proprio lavoro, è quasi tautologico, ma la cosa fondamentale secondo me è nella produzione di software, spesso i pensieri sono volatili e se non si trasformano subito in codice si rischia di perdere i processi logici.

Questo tipo di documentazione non è direttamente legato al codice sorgente e può essere considerata una tecnica di tipo generale che si applica anche ad altri argomenti non direttamente collegati alla produzione di software, ad esempio progetti gestionali operativi, processi sistemistici ed altre cose del genere.

L'utente finale

Oltre alla documentazione del codice sorgente che serve per scrivere software più robusto ed efficente, esiste ed è necessario scrivere la documentazione per l'utente finale.

Il concetto è che se un procedimento non è documentato e l'utente non lo consce, di fatto rimane inutilizzato e quindi è come se non ci fosse. Di più, se non documentiamo il nostro programma può capitare, ed a me è capitato, di non ricordare che una funzionalità richiesta era stata già stata implementata in precedenza e di scoprirla solo al momento del bisogno.

Devo dire la verità, spesso gli utenti non leggono la documentazione e preferiscono chimare il tecnico della manutenzione per chiedere come si fa una cosa. Ma questo non importa, sarà il tecnico che con la propria esperienza saprà se una funzionalità è stata implementata oppure no e poi andando a leggere la documentazione ne controllerà l'esatto funzionamento.

Per scrivere la documentazione per gli utenti, a differenza del codice sorgente si possono usare diversi mezzi, gli applicativi desktop, di solito hanno guide contestuali in linea che permettono di ottenere le istruzioni specifiche direttamente dal punto in cui ci si trova. Il testo delle guide solitamente è scritto in html, oppure con programmi tipo Word o LibreOffice, spesso nel testo sono accluse immagini delle form di qui si parla.

Gli applicativi web invece solitamente non hanno guide in linea, al massimo hanno qualche finestra pop up che compare quando si posiziona il mouse su specifiche posizioni. Solitamente i programmi web sono meno articolati e dispongono di meno di funzionalità, questo perché sono spesso indirizzati a utenti occasionali e devono essere facili da usare, se proprio serve spiegare qualcosa, di solito la spiegazione è mescolata nel codice html della pagina in uso.

Il discorso è diverso per la parte amministrativa dei siti, in questo caso gli utenti sono fissi ed hanno compiti più complessi, per questo motivo la documentazione deve essere adeguata. Per i CMS più diffusi come ad esempio WordPress, Joomla!, Typo3 e tutti gli altri, sono disponibili innumerevoli libri, tutorials e guide. Se scrivete applicativi web che prevedono un backend, dovrete in qualche modo fornire qualche tipo di documentazione.

Se nella descrizione della documentazione del codice dicevamo che la prima documentazione era la chiarezza della scrittura, allo stesso modo per la documentazione per l'utente la prima cosa da fare è fare in modo che il programma sia chiaro, che le funzionalità siano logiche e che seguano il senso comune e sopratutto che i comportamenti siano consistenti. In questo senso la stessa icona deve sempre indicare lo stesso comportamento e lo stesso tasto svolgere il medesimo compito. Questo comporta una maggiore facilità di apprendimento ed una migliore soddisfazione per l'utente che deve imparare meno cose.

È anche importante gestire il controllo di versione, l'utente deve sapere quale versione del programma sta utilizzando e da una versione all'altra deve sapere quali novità sono state introdotte che richiedono la sua valutazione.

La documentazione per gli utenti finali può essere di diversi tipi, tutti più o meno necessari e tutti più o meno separati o inclusi nello stesso documento:

Il Manuale utente dovrebbe spiegare i processi logici del programma che ne rappresentano per così dire il suo "modo di pensare", e dovrebbe essere in grado di guidare l'untente alla realizzazione dei compiti dall'inizio alla fine, ad esempio per un programma gestionale dovrebbe spiegare come si parte da un ordine per arrivare ad una fattura e nel contempo indicare le caratteristiche degli articoli di magazzino e di clienti e fornitori.

Il Manuale di riferimento invece dovrebbe elencare in modo puntuale tutte le opzioni di un determinato elemento, ad esempio per le anagrafiche dei clienti dovrebbe elencare tutti i campi richiesti cono il loro significato e le implicazioni per il resto del programma.

I Tutorial e documenti simili come pagine wiki, blog o video invece spesso si occupano di un singolo aspetto delle funzionalità del programma e servono per arricchire la proposta e facilitare e favorire l'uso di quelle parti del programma.

In ogni caso si deve ricordare, che se una funzionalità del programma non è documentata, è come se non ci fosse. Si può omettere di documentare solo per le parti di programma si si desidera intenzionalmente escludere per proteggere funzionalità potenzialmente pericolose che sono destinate al personale che fa la manutenzione.

Come per la documentazione del codice sorgente, anche la documentazione per l'utente rappresenta l'ultimo passo prima del deploy della versione. Prima si scrive e si testa il codice, alla fine si scrive la documentazione e si pubblica la release. Ed anche in questo caso è bene che venga scritta immediatamente in modo da descrivere i flussi logici in modo correto e per evitare di dimenticarsi di farlo in seguito.

Quanto costa fare la documentazione?

Forse per i porgetti di piccole dimensioni, la documentazione potrebbe rappresentare un costo, ma sicuramente per i progetti di medie o grandi dimensioni rappresenta un risparmio netto.

La documentazione del codice sorgente aiuta a scrivere software più robusto e meno rindondante ed in ultima analisi a scrivere di meno codice.

La documentazione per l'utente finale d'altro canto fissa le funzionalità dei programmi aumentando la chiarezza e diminuendo costi e tempi da dedicare all'assistenza.

Strumenti per la documentazione

Alla fine di questa trattazione esaminiamo alcuni stumenti che trovo utili per la redazione della documentazione.

Editor di testo

Ovviamente, trattandosi di scrivere del testo, il primo strumento è un editor di testo. Di norma non amo usare un WordProcessor come ad esempio LibreOffice, perché usa un formato strutturato, preferisco il testo semplice o al massimo se ho necessità di arricchire il testo uso markdown o RestructuredText che vengono trasformati facilmente in testo html, e magari possono essere convertiti in altri metalinguaggi con l'utility pandoc.

Come tutti i programmatori sono sempre interessato a provare nuovi editor di testo evoluti anche se è difficile cambiare perché richiede sempre un certo sforzo imparare nuovi comandi. Ultimamente uno dei miei favoriti è Visual Studio Code, ma ce ne sono altri di interessanti, ne elenco alcuni:

Nome	OS	Caratteristiche
Visual Studio Code	Win, Mac, Linux	Potente editor ed IDE multilinguaggio che funziona a plugin
Sublime	Win, Mac, Linux	Simile a vscode ha molti sostenitori ma soffre la concorrenza del precedente (IMHO)
Geany	Linux, Win	Editor tradizionale leggero ma abbastanza ricco di funzioni
PSPad	Win	Editor leggero e veloce ricco di funzioni
Notepad++	Win	Uno dei più usati in ambiente Windows, usa anche plugin
Notepadqq	Linux	Simile a Notepad++

IDE

Oltre agli editor semplici per molti linguaggi sono disponibili ambienti IDE (Integrated Development Environment) che in un unico ambiente mettono a disposizione tutti gli stumenti necessari allo sviluppo tipo gestore di progetto, editor, compilatore e debugger. Nel elenco alcuni

Nome	OS	Linguaggio	Caratteristiche
PyCharm	Win,Mac,Linux	Python	Potente e diffusa IDE per Python
AndroidStudio	Win,Mac,Linux	Android	Il sistema di sviluppo di riferimento per Android
Eclipse	Win,Mac,Linux	Vari	IDE configurabile per vari linguaggi
NetBeans	Win,Mac,Linux	Vari	IDE configurabile per vari linguaggi
VisualStudio	Win	Vari	L'ambiente di riferimento per la programmazione windows

Non mi vorrei dilungare oltre sulle IDE, ce ne sono molte. Vorrei solo accennare al fatto che Sublime e VSCode sopra citati possono essere considerati anche IDE dato che dispongono anche di comandi molto potenti per la gestione integrata dello sviluppo.

Spesso le IDE dispongono di comandi specifici per la gestione della documentazione. Come dicevo all'inizio, alcuni linguaggi hanno regole specifiche per la stesura dei commenti, se si seguono, alcune IDE sono in grado di mostrarci la documentazione nel momento che la usiamo.

Digressione

Non tutti sanno che il primo strumento che può essere chiamato IDE fu il TurboPascal che funzionava sotto MS-DOS e all'epoca fu un prodotto innovativo perché metteva a disposizione ad un costo limitato un ambiente di programmazione evoluto e facile da usare.

Il principale progettista, Anders Hejlsberg, molti anni dopo fu assunto da Microsoft e divenne ingeniere capo del progetto C# e .NET

Documentazione automatica

Come abbiamo già detto, se si seguono alcune regole, per molti linguaggi sono disponibili strumenti automatici che producono la documentazione, esistono stumenti di questo tipo per Java, C#, Python e molti altri. Il vantaggio è che siccome lo sviluppo del software è un lavoro dinamico, la documentazione automatica consente di tenere sempre aggiornata la documentazione senza intervento manuale che può essere soggetto ad errori.

Altro strumento interessante ma meno diffuso è il "Cross reference". Quando si sviluppa un sistema di grandi dimensioni, sarebbe bello sapere in quali posizioni del sorgente sono state usate determinate funzioni o classi. Spesso le IDE permettono di fare ricerche in tutti i files del progetto, però questo richiede che i nomi da cercare siano abbastanza riconoscibili ed univoci e non sempre è così, uno strumento completo dovrebbe essere in grado di fare il parsing del sorgente per fare in modo di individuare le stesse porzioni di codice individuate dai compilatori o dagli interpreti.

Altri stumenti

Oltre a tutti gli strumenti indicati, elenchiamo anche alcuni tools o tecnologie che forse non possono essere considerati come strumenti di documentazione in senso stretto, ma comunque vengono utilizzati in fase di sviluppo.

git è uno strumento di controllo di versione che aiuta a produrre sofware migliore ed affidabile il suo uso e specialmente l'uso di GitHub e GitLab, portano a documentare le fasi di sviluppo.

Unit Testing come detto in precedenza le tecniche di Unit Testig sono di per se stesse documentazione, infatti se si testano tutti i comportamenti possibili di una funzione o classe, la lettura del test di dice quali sono i comportamenti attesi.

Sphinx basato su python e restructudedtest, è uno strumento apposito per produrre documentazione in html ben strutturata. È molto usato in ambiente python, ma non solo. il sito ReadTheDocs è uno dei principali repository per la documentazione di librerie python.

HtmHelp In ambiente Windows uso questo strumento per compilare testi html nelle guide native di Windows.

BoostNote in questo ultimo periodo trovo interessante questo programma per la stesure di note che possono essere raggruppate per argomento e tags.

altri ancora nel mare grande di internet ovviamente si trovano tantissimi altri strumenti, io ho citato solo quelli che conosco e che uso. Se desiderate, mi potete segnalare altri strunenti importanti ed io sarò felice di aggiungerli a questa lista.

Questo documento

Questo documento è stato scritto con BoostNote in formato markdown e tradotto in MediaWiki con Pandoc

Io

Mi chiamo Claudio Driussi, mi occupo da molti anni di sviluppo di software gestionale.

Per commenti e suggerimenti mi potete mandare una mail a claudio.driussi@gmail.com

La documentazione del software

Contents