Newsgroup: it.comp.lang.delphi
Titolo: [ot] come si documenta il software

ciao a tutti, avendo un software particolarmente complesso, formato da tante 
form, tante tabelle e varie procedure esterne mi sono chiesto come sarebbe 
meglio documentarlo... nel senso che ora lo modifico solo io, ma in futuro 
magari io potrò non ricordare il funzionamento e/o potrei aver bisogno di 
delegare altre persone allo sviluppo... voi come vi comportate??? classico 
manuale in excel scrivendo le cose principali?
Simo 


prima di tutto commentando bene il codice,
per ogni funzione/procedure, la funzione, i parametri eventuali valori 
che ritorna.
per le variabili (almeno le principali), dare un commento sull'utilizzo.
dividere i moduli in base al contenuto.
scrivere in modo ordinato
..........
-- 
-------------------------------
per scrivere in privato
togliere "1975nosp"
to reply remove "1975nosp"


Magari in Word, tanto per non complicarsi la vita. :-D
Ciao
Marco 

Se parliamo solo del codice, oltre a usate uno standard per intentazione 
e nomencaltura, si deve stare attenti ai commenti.
Se ve ne sono troppi, rischi di perderne il controllo e potrebbero non 
essere allineati alle ultime variazioni del codice, e questo, secondo 
me, puo essere + deleterio della assenza di commenti.
Su un vecchio libro trovai alcune semplici indicazioni che uso ormai da 
un pezzo:
1) Nomi di variabili chiari
Io, ho il repgio/difetto di usare nomi lunghi, ma preferisco perdere + 
tempo a scrivere che a ricordarmi il significato di un acronimo
2) usare i commenti sopratutto per spiegare non COSA FA IL CODICE, ma 
PERCHE' LO FA: il cosa fa lo capisci leggendo il codice stesso
3) Questa è un mattone: "SE NON RIESCI A TROVARE IL NOME DA DARE AD UN 
METODO IL METODO E' SCRITTO MALE."
Se sviluppi in MDA e usi uno strumento per la modellazione come Sybase 
Power Designer viene automatico trovarsi la documentazione.
Puoi indicare una breve descrizione per ogni classe, metodo, parametro, 
aggiungere al modello delle business rule, con gli uses case descrivi i 
vari task che la applicazione deve prevedere e puoi associare ad ognuno 
di essi le classi necessarie alla sua corretta esecuzione e tanto, 
tanto, tanto altro....
Presumo che anche strumenti come Rose, EA e lo stesso delphi200x preveda 
qualcosa..
AS

 manuale in excel scrivendo le cose principali?
Ci sono dei tools di autodoc che fanno tutto quello che vai cercando:
commentando il sorgente nel modo gia' spiegato nel thread, e delimitando
questi commenti con appositi tags, puoi lanciare questi tools che ti
producono file html, pdf, chm, hlp... insomma un formato portabile.
Ricordo che Guastatore e' un mostro in questo campo, getto la palla al
balzo all'amico scacchista :-)
-- 
Morde. 
ICLDweb: 
http://www2.samatel.com/icld/

Morde ha scritto:

Personalmente uso doxygen (che e' forse il piu' conosciuto tool 
javadoc-like) per C++ e in accoppiata con pas2dox per Delphi.
Il tutto open-source, quindi a costo zero.
pas2dox ha qualche problemino con sorgenti complessi.
Esistono altri tool simili, anche specifici per Delphi.
DelphiCodeToDoc (su 
sourceforge.net
), ad esempio, sembra buono.
Ci sono anche tool commerciali, ma non ne ho usati (a parte qualche 
trial di un paio di loro qualche anno fa, ma mi sembravano o scarsi o 
troppo complicati).
Alcuni di questi tool richiedono una sintassi specifica per i "tag" nei 
commenti. Tendenzialmente e' meglio se si adeguano alla sintassi usata 
da JavaDoc, che e' piuttosto diffusa in diversi ambiti (java, c++, 
Windows, Linux).
-- 
Roal Zanazzi

Simone P. ha scritto:

L'argomento e' piuttosto vasto...
A parte i sacrosanti suggerimenti su come, quanto e quando scrivere 
commenti nel codice sorgente che altri hanno gia' scritto;
se un software e' complesso sarebbe meglio avere un documento che ne 
descrive l'architettura ad alto livello, senza entrare nei dettagli, 
magari in modo schematico (meglio un disegno piuttosto che mille parole).
Excel? Perche' complicarsi la vita?
A volte basta un file di testo e una immagine scannerizzata di uno 
schema fatto a mano, oppure usi il tuo word processor preferito (io uso 
OpenOffice Writer + OpenOffice Draw per alcuni schemi).
Alcuni (seguaci dell'eXtreme Programming) ti diranno che la migliore 
documentazione e' il codice sorgente dell'applicazione e dei suoi vari 
testcase; opinione interessante e non priva di verita', ma io preferisco 
un approccio piu' "top-down", prima voglio capire cosa fa il software e 
quali sono le sue parti principali, poi entro nei dettagli.
-- 
Roal Zanazzi

grazie a tutti per le risposte... il codice è già commentato dove serve 
(ovviamente) e le variabili seguono lo standard letto in alcuni testi di 
pascal (es: nTotale, cStr, lBool, ecc).. mi domandavo come partire a 
scriverla... in word pensavo di mettere elenco delle form, spiegazione con 
foto e commenti sugli eventi principali
Simo 

 getto la palla al balzo all'amico scacchista :-)
Esagerato ! :-) ma tin ringrazio al solito della considerazione. ;)
Rispondo a Roal Zanazzi che ha citato entrambi i software che ho
provato per la documentazione dei sorgenti.
Ciao !
Antonio
-- 
guastatore
ICLDweb: 
http://www2.samatel.com/icld/

 c++, Windows, Linux).
Credo anche io sia più opportuno usare la sintassi javadoc.
Ciao


 
Se sviluppassi ancora a tempo pieno in Delphi mi piacerebbe dare una 
mano al progetto, ma al momento (e credo per i prossimi anni) sono 
passato a progetti C++ e il tempo non basta mai!
-- 
Roal Zanazzi

 passato a progetti C++ e il tempo non basta mai!
Disserto in OT un attimo ripensando al concetto del lavoro e del tempo che
non basta mai: ricordo le pubblicità degli anni 60 in america dove
profetizzavano che, con l'avvento del calcolatore, l'uomo avrebbe avuto più
tempo per passarlo con la famiglia (tipica famiglia anni 50 americana)
mentre il pc faceva di conto.
Tralasciando le montature del marketing americane di quegli anni di guerra
fredda, il pensiero poco confortante che mi viene è che per noi che
lavoriamo sul computer, le ore richieste da passare davanti al monitor e
con le mani alla tastiera sono sempre di più.... invece che diminiure...
Bah!
pensiero malinconico del giovedì sera...


 
Rincaro la dose:
per noi che "lavoriamo sul computer" le ore richieste davanti al monitor 
sarebbero molte meno se avessimo degli strumenti migliori, qualcosa che 
ci permettesse di focalizzare gli sforzi sulle idee, invece che sulla 
sintassi, sull'allocazione di risorse, etc...
Pensateci bene, gli informatici progettano e costruiscono un'infinita' 
di software per risolvere i problemi degli altri, ma pochi (e 
decisamente lontani da cio' che e' veramente utile) per la propria 
categoria.
Dopotutto cosa si puo' pretendere, se nel 2006 usiamo ancora dispositivi 
di input obsoleti, e una tastiera la cui disposizione di tasti era nata 
per _rallentare_ la digitazione (per non far incastrare le bacchette 
delle vecchie macchine da scrivere meccaniche)! <g>
-- 
Roal Zanazzi

ma poi quando si aggiorna il codice per nuove release o per bug risolti in
futuro... bisogna ovviamente aggiornare anche la documentazione o sbaglio??
alla fine  è un lavoro molto impegnativo e spesso il tempo non è mai
abbastanza (ne per il tempo libero ne per le cose da fare )
Simo

Simone P ha scritto:

Infatti e' anche per questo che preferisco scrivere un documento _solo_ 
per l'architettura ad alto livello: questa cambia relativamente poco nel 
tempo di vita di un progetto.
I dettagli implementativi dovrebbero essere documentati nel codice (e 
mantenuti aggiornati insieme ad esso).
Per i bug risolti e le nuove feature il discorso e' un po' diverso, qui 
entrano in campo sistemi e processi di Configuration Management (come 
minimo un buon software di versioning e di bug tracking), meglio se 
integrati o integrabili tra loro (in modo che si possa legare una 
segnalazione di bug o una Feature Request con i file/revisioni 
modificati per il fix/implementazione).
In questo caso e' il sistema di CM che "documenta" l'origine, 
l'evoluzione e l'elenco delle modifiche, non i commenti nel codice sorgente.
-- 
Roal Zanazzi

 pascal (es: nTotale, cStr, lBool, ecc).. mi domandavo come partire a
e' piu' da clipper che da pascal questo standard :))
-- 
===============================================================
Alberto Rubinelli - A2 SISTEMI  Opera 8.50
Via Costantino Perazzi 22 - 28100 NOVARA - ITALY
Tel 0321 640149  Fax 0321 391769 BBS 0321 392320
Mail: 
alb...@retrocomputing.net
  ICQ : 49872318
Skype : albertorubinelli
Visita il mio museo di computers - Visit my old computers museum
 
http://www.oldcomputers.it
---------------------------------------------------------------

ops mi sa che me lo son portato avanti da quando usavo clipper... mi hai 
beccato!!!!
Simo 

 e' piu' da clipper che da pascal questo standard :)
Veramente non saprei... io usavo questa notazione in c++! :-D
