Stavo attrezzando un piccolo progettino scemo sulle OpenGL (più didattico che altro) e così ho pensato di condividere quelle regole non scritte che servono ad organizzare e gestire un progetto software. Sono piccole “tips”, struttura delle cartelle e file che non devono mai mancare. Presenterò anche altri strumenti, come ho fatto per Python, ma questa volta saranno strumenti “generici”, ovvero utilizzabili con qualunque linguaggio.

Questo perché tenere in piedi un progetto male organizzato è come costruire un castello di carta. Ci vuole una base forte per rendere il più accogliente possibile il progetto per le persone interessate a collaborare, sia per i membri del vostro team (se ne avete uno).

STRUTTURA CARTELLE

Le cartelle vanno organizzate in modo piuttosto coerente. È importante non mischiare tutto in poche cartelle confuse specialmente per progetti destinati a crescere rapidamente. Una struttura minimale è la seguente:

• src – La cartella src contiene il codice sorgente. Il codice al suo interno può essere organizzato come si desidera in accordo con le convenzioni del linguaggio. L’importante è che contenga solamente il codice del programma/libreria.
• test – La cartella test contiene il codice sorgente dedicato ai test. Il codice di test serve a provare il corretto funzionamento delle classi sviluppate o di alcuni moduli software oppure possono essere semplicemente test prestazionali.
• build – La cartella build contiene tutti i file ottenuti come residuo di una compilazione. Possono essere moduli parziali C/C++ (.o), classi Java (.class), file python compilati (.pyc) e così via. La cartella va a sua volta divisa nelle varie configurazioni di compilazione (ad esempio ci potrebbe essere una configurazione Debug con compilati ottimizzati per il debug e una configurazione Release con compilati ottimizzati per le prestazioni).
• dist – La cartella dist contiene il prodotto finito. Può essere il programma eseguibile, un file .jar, una libreria .so e così via. Tutto quello che sta in dist deve essere pronto per essere eseguito e distribuito.
• doc – La cartella doc contiene la documentazione dettagliata. Tale documentazione è per lo più la specifica dettagliata delle API la quale è solitamente auto-generata.

FILE MUST

Nella cartella radice sono necessari alcuni file. Necessari è una parola grossa in quanto solitamente il programma funziona benissimo anche senza, ma sono un tocco di classe e di umanità verso chi vuole accedere ai sorgenti della vostra applicazione.

• Tool di compilazione - Sia Makefile, o Cmake o qualunque altro tool utilizzate… DEVE esserci uno strumento per la configurazione e la compilazione. Molti IDE possono anche auto-generare roba simile.
• README – Il readme deve dire vita morte e miracoli sull’applicazione. Deve spiegare come può essere compilata  l’applicazione, quali sono le dipendenze, i bug noti, etc..
• README.src – Per applicazioni il cui README è eccessivamente complesso è bene separare le informazioni per sviluppatori in un file a parte. Il file README.src deve spiegare come è organizzato il codice, quale IDE si è usato (se si è usato), quale librerie di sviluppo servono, quale strumenti si sono usati per generare la documentazione, per i test e per altro. Insomma… tutto ciò che può essere utile per chi è interessato alla modifica del codice.
• COPYRIGTH - Il file che contiene le informazioni sulla licenza del progetto.
• CHANGELOG – Il file che contiene la lista dei cambiamenti apportati al programma nel corso della sua storia. Questo file può essere auto-generato da alcuni sistemi di CVS.

DOCUMENTAZIONE

Scrivere a mano la documentazione è sempre l’ultimo dei problemi. Nonostante ci siano molte cose che debbano necessariamente essere scritte a mano, per le API è possibile usare dei tools automatici. Abbiamo visto Epydoc per python. Bene, per tutto il resto c’è Doxygen. Doxygen è un programma di auto-generazione della documentazione utilizzabile per una miriade di linguaggi.

CVS

Il programma per CVS è essenziale se programmate in gruppo ma è molto utile anche se programmate da soli. Vi permette di manipolare il codice con molta disinvoltura navigando fra branch diversi in modo del tutto trasparente.

Potete usare quello che vi pare come CVS anche se io consiglio sempre GIT. Lo trovo molto più veloce ed elastico dei concorrenti. Se volete convincervi potete sempre andare su http://it.whygitisbetterthanx.com/

MESSAGGISTICA

Ebbene si. Se avete un gruppo di persone con cui lavorate insieme non potete prescindere da un sistema rapido e veloce per lo scambio di informazioni, siano esse “OMG! Non funziona una cippa!” o messaggi più tecnici.

A questo punto avete le basi. Non vi resta che seguire questi consigli e lanciarvi nel tempestoso mondo del software libero sperando che il vostro progetto non sia un castello di carte spazzato via dal vento.

Java aveva un lato positivo. C’era una cosa che mi piaceva: javadoc. Ovvero un sistema per generare automaticamente una dettagliata e affascinante pagina web con la descrizione e la documentazione di ogni parte di codice scritto basandosi su alcuni speciali commenti del codice.

Ma io non sono un programmatore Java (dio me ne scampi) ma, fra i molti linguaggi, mi diverto con il Python. Così ho cercato in lungo e in largo un sistema che svolgesse le stesse funzioni di Javadoc. E l’ho trovato.

Python dispone di molti tool del genere, quindi ne ho provati un po, fino a far ricadere la mia scelta su Ephydoc. Ephydoc non solo svolge tutte le funzioni di javadoc ma è molto più potente e versatile.

Innanzitutto per istallarlo, come ormai sappiamo, digitiamo dal terminale:

# apt-get install python-epydoc

A questo punto il programma è pronto per essere utilizzato. L’importante è commentare il nostro codice seguendo delle piccole cose a mente.

Innanzitutto epydoc sfrutta la docstring standard di Python. Dovete sapere che Python integra nativamente un piccolo sistema di documentazione nel codice. Infatti proviamo a scrivere una funzione in questo modo:

def codice_esatto(code):
    """
    Verifica se il codice inserito è corretto.
    """
    if codice=="4 8 15 16 23 42" :
        return true
    else :
        return false

Il testo racchiuso fra le triple virgolette è una stringa che descrive la funzione codice_esatto. Infatti digitando dall’interprete:

>>> print codice_esatto.__doc__

Ci viene restituito proprio il testo fra virgolette.

Epydoc sfrutta proprio questo testo per comporre la pagina web e inoltre è possibile aggiungere alcuni elementi di markup per rendere la documentazione più elegante.

Per una guida completa alla documentazione vi rimando alla pagina ufficiale del manuale di epydoc dove ci sono molti esempi di facile interpretazione. Qui di seguito aggiungo una serie di tag di frequente utilizzo:

• @param p: Descrizione del parametro p
• @type p: Tipo del parametro p
• @return: Descrizione del valore restituito.
• @rtype: Tipo del valore restituito.
• @raise e: Descrizione sulle circostanze in cui viene lanciata l’eccezione e

Per il resto rimando sempre al sito ufficiale.

Una volta che abbiamo commentato tutti i nostri file (dovrebbero essere già commentati. Se non lo sono aih aih aih, è la regol aprima del programmatore) non ci resta che lanciare epydoc con:

epydoc file1.py file2.py ... fileN.py

Alla fine troveremo tutta la nostra documentazione nella cartella html. Buona lettura