[Php-it] [semi-ot] Programmazione

[Andrea Franceschini]

Il 06/04/07, Gianluca Baù<gianluca a ihuri.it> ha scritto:

> Voi tenete una documentazione (cartacea/digitale) su un lavoro (da
> mediamente complesso in su) che state portando avanti ?
> La aggiornate periodicamente? Come la strutturate?

Per progetti di piccole dimensioni e/o cose relativamente personali mi
limito a commentare abbastanza bene il codice, tipo le classi, i
metodi, alcuni passaggi... così da poter avere un riferimento da
phpdoc se necessario e alcuni passaggi ben documentati all'interno del
codice. Di solito procedo scrivendo il codice e appuntandomi le cose
su un foglio di carta, perché mentre il codice è ancora molto
malleabile è veramente seccante girare attorno a commenti di una certa
dimensione :D Come esempio da non seguire, ho trovato in diversi
software parti di codice abbastanza incomprensibili commentate dallo
stesso autore con "I don't know what's this for, but if removed
nothing works". Spesso questo è anche indice del fatto che chi ha
scritto il codice non si è ben documentato sulle librerie che usa (di
solito commenti del genere si accompagnano a particolari parametri che
sfuggono all'intuizione o ad altre cose così).

Per progetti medio-grandi mi sono abituato a "lavorare in grande"
sempre, specie quando si tratta di farsi pagare :D Fisso sempre una
data di fine, passo un 10-15% del tempo totale a raccogliere
requisiti, buttare giù idee, organizzare le informazioni - se lavoro
con altre persone è facile che ci si trovi per una sessione di
brainstorming - e poi faccio proprio le cose in grande, stabilendo un
grado di rigidità in relazione al tipo di lavoro/cliente, faccio una
piccola WBS, fisso deliverable, milestone e altre cose del genere,
assegno compiti (sempre se lavoro in gruppo) e produco una tabella di
marcia che sarà tanto più rigida quanto più è prioritario il lavoro
(se ho un contratto da 5000 euri sicuramente rispetterò tutti i
vincoli temporali e tralascerò ben volentieri i vincoli di un progetto
personale parallelo :)

Per quanto riguarda la documentazione, al di là del codice, di solito
decido in base a chi dovrà usare il programma. Se sono io,
difficilmente la scriverò, se è una segretaria le scriverò le
istruzioni per l'uso, se è una piattaforma per sviluppatori descriverò
in dettaglio l'API, classi, proprietà, metodi... per un paio di
progetti su cui ho lavorato recentemente, ho tenuto tutta la
documentazione prodotta nelle varie riunioni di avanzamento e abbiamo
prodotto una documentazione finale relativa all'uso del prodotto
finale e una documentazione per gli sviluppatori che volessero usare
l'API. Ci siamo armati di LaTeX e via.

In ogni caso, il punto critico è sempre decidere "quando" scrivere la
documentazione. Tutto rigorosamente IMHO, a priori si può scrivere una
descrizione dei requisiti del programma, durante si possono
documentare in maniera minimale i pezzi di codice, le funzioni (tipo
"questo prende questo e sputa fuori quest'altro") e alla fine si
raffinano e completano le doc delle funzioni ed eventualmente si può
correggere il tiro di quanto già scritto, in una sorta di retroazione.
Lo scrivere prima i requisiti è ottimo per poter riguardare in corso
d'opera cos'avevo deciso di fare e confrontarlo con eventuali
problematiche che sorgono, così posso rimaneggiare il codice senza il
rischio di allontanarmi troppo dall'obiettivo prefissato.

Spero di aver scritto tutto.