.: HosiriS :.

Informatica e non solo

L’importanza della documentazione

Posted by hosiris su giugno 23, 2010

I “programmatori” autodidatti (come me) hanno sempre avuto un difetto: basano i loro studi sulla sintassi del linguaggio, ma non tengono mai in considerazione l’importanza di dover documentare il codice che viene scritto. Si da per scontato che un altro programmatore sia in grado di leggere e comprendere il sorgente che gli viene messo davanti. Certo se parliamo di progetti basilari, in cui non vengono usate librerie strane e in cui il codice non super le 50 righe questo è vero, ma pensiamo a progetti che comprendono più di uno sviluppatore, che prevedo sorgenti complessi con richiami continui a librerie… diventa impossibile capire cosa si ha davanti.
Ecco che diventa di importanza vitale il saper commentare il codice. Direi che è importante quanto scrivere del buon codice.
Credo sia nelle conoscenze di ogni “programmatore” la metodologia con cui un linguaggio accetta dei commenti, quindi una documentazione di base rientra nelle capacità di tutti, basta essere sufficientemente completi, tanto i commenti non vengono compilati, possiamo scrivere 1000 righe di commento per una funzione senza avere dei risultati negativi sull’esecuzione del programma.
Oggi a queste conoscenze di base, voglio aggiungere l’uso di uno strumento che ci permette di creare della documentazione più facilmente leggibile: Doxygen.
Il programma può essere installato facilmente da repository:

$ sudo apt-get install doxygen

mentre l’interfaccia grafica va scaricata, anche se esiste un deb.
Seguendo il manuale è facile capire come sia possibile personalizzare i commenti. Ad esempio consideriamo il seguente codice:

#include <iostream>

/** @brief Funzione di visualizzazzione
  * Tramite questa funzione viene stampato a video un messaggio di saluto
  * @author io
  * @date oggi
  */
void echo(){
  cout << "CIAO" << endl;
}

/** @brief Corpo principale
  */
int main(){
  echo();
  return 0;
}

Salviamo il codice e apriamo la gui di doxygen tramite il comandi doxywizard:

Inseriamo i dati necessari, poi scegliamo il tab RUN e poi Run doxygen. Aspettiamo che vengano terminate le operazioni e poi possiamo visualizzare il risultato.
Personalmente preferisco il formato tex in quanto una volta compilato ci permette di avere un manuale, ma il formato html ci permette una navigazione più semplice.

Buon divertimento

Lascia un commento

Inserisci i tuoi dati qui sotto o clicca su un'icona per effettuare l'accesso:

Logo WordPress.com

Stai commentando usando il tuo account WordPress.com. Chiudi sessione / Modifica )

Foto Twitter

Stai commentando usando il tuo account Twitter. Chiudi sessione / Modifica )

Foto di Facebook

Stai commentando usando il tuo account Facebook. Chiudi sessione / Modifica )

Google+ photo

Stai commentando usando il tuo account Google+. Chiudi sessione / Modifica )

Connessione a %s...

 
%d blogger cliccano Mi Piace per questo: