SlashCode

Come organizzare un progetto

Posted on 24. May, 2010 by THeK3nger in Generale

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.

Tags: cvs, documentation, featured, git, programmazione