Newsgroup: it.comp.lang.visual-basic
Titolo: Documentazione di un programma VB

Ciao a tutti,
Intanto mi interessa capire se effettivamente serve la documentazione
di un programma implementato,
l'ho detto al capo (che ha anni di esperienza in più rispetto a me) e
mi ha riso in faccia....semmai
me la faccio in casa così tra 6 mesi quando sarà ora di riprendere in
mano il codice gli rido in faccia io!..
Nel caso in cui credete sia una cosa utile, sapreste indicarmi la
maniera migliore per scriverla? magari ne esiste una universale...
Un esempio? un articolo esplicativo? qualcosa del genere...
Grazie a tutti, babbomarcello

 ha scritto nel messaggio 
news:be9e593b-d50d-4887...@k41g2000yqn.googlegroups.com...


 Ipotesi:
zac
Io spero che tu stia scherzando!
Lui non sta parlando del manuale d'uso!!!
La documentazione di un programma per un programmatore NON E' il
manuale d'uso!!!
Se fai questa confusione...mamma mia...spero non si traduca in codice!
La documentazione di un programma....serve fra 6 mesi...quando hai da
inserire una NUOVA stampa....serve a sapere SUBITO...dove agganciare
un nuovo report...quale recordset/interfacce/ocx quello che vuoi
collegare...
Per dire io uso in un progetto reportman....nella procedura X ci sono
gli agganci ai vari report: la definizione della connessione e il nome
della query sql da passare.... nella formXX e nella procedura XY la
lista dei report.
Aggiungere una nuova stampa non è che:
Avviare il designer di reportx e farsi il NUOVO report e salvarlo in
un file
Aggiungere SEMPRE il file del report in una cartella ad hoc (con
sforzo di fantasia Report) parametrizzata all'installazione
Aggiungere 1 Nuova query e 3 nuove righe nella procedura X
Aggiungere 3 righe nella procedura XY della form XX
...tutta questa serie di operazioni la faccio in 3 minuti (tranne
sviluppare la stampa che mi porta via più tempo a causa delle mille
"carinerie" grafiche che gli utonti desiderano)...!
Ora
dopo 6 mesi
Vatti a ricordare tutta la sequenza?
Aggiungo che questo sistema vale per una vecchia applicazione che ha
poche modifiche...e necessita di ricompilazione!
Se dovessi fare una modifica per aggiungere o togliere menu e stampe a
runtime?
Traccia delle modifiche?(se un cliente non vuole upgradare?)
Nuovo modo di operare?
Tutte queste info vanno scritte...
pensa se  vinci un mese ai caraibi e lasci tutto ai tuoi soci!...per
un mese non aggiungi stampe?
O non modifichi il numero di licenza...o il logo iniziale...o la
codifica di un codice a barre???
Via...stai scherzando vero???


Quello che realmente serve è che il codice sia scritto nella maniera più
chiara possibile.
Anzi, direi quasi che dovrebbe essere il più banale possibile, evitando
di "fare i furbi", magari tentando di ottimizzare il codice rispetto
alla velocità (anche perché, probabilmente, il compilatore sa molto
meglio di noi come ottimizzare determinati frammenti di codice).
Questa chiarezza nel codice si ottiene con i soliti semplici
accorgimenti, che ormai dovrebbero sapere più o meno tutti (e che
comunque dovrebbero essere dettati dal buonsenso)
Ne elenco alcuni:
- uso delle costanti
- uso dei tipi enumerati
- dare nomi esplicativi a variabili e funzioni
- scrivere routine brevi (personalmente, raramente vado oltre 2/2.5
pagine, tranne ovviamente casi particolari)
- non annidare tra loro più di 3 cicli
- in modo analogo, evitare di annidare troppi if
- evitare di scrivere troppo codice sulla stessa linea
- qui andiamo più sulla forma, comunque a me piace (quando possibile)
evitare che una linea di codice ecceda i 90, massimo 100 caratteri
- evitare di trovarsi con troppi livelli di indentazione all'interno di
una routine (nuovamente, per quanto mi riguarda, mai più di tre partendo
a contare come livello 0 quello immediatamente successivo alla
dichiarazione della routine stessa).
I commenti al codice sono importanti, ma come per tutte le cose, bisogna
imparare bene a scriverli. Non devono essere banali (del tipo
"incremento di uno il contatore del ciclo") e nemmeno prolissi.
Se, mentre scrivi un commento, ti accorgi che stai spiegando *come* quel
frammento di codice fa una certa cosa, vuol dire che molto probabilmente
stai sbagliando qualcosa.
Un commento dovrebbe spiegare *che cosa* fa il codice, non il come.
Se ti occorre spiegare dettagliatamente a parole come il tuo codice
svolge un determinato compito, probabilmente hai scritto del codice che
sarebbe meglio buttare giù per la turca.
Calcola poi che i commenti vanno "mantenuti in forma" e quindi se sono
pochi (perché il tuo codice si spiega da solo), fai anche presto a farlo.
Piuttosto di trovare commenti fuorvianti perché vecchi rispetto al
codice, io preferirei che non ce ne fossero affatto.
-- 
S.


Il codice dovrebbe essere solo e soltanto "codice"...non una pagina di
"guerra e pace"!
L'uso di comenti andrebbe evitato il più possibile!
Se un commento in testa ad un modulo di classe dovrebbe essere la
regola....commenti sparsi a pioggia sono da evitare!
Il punto è:
NON DEVO fra 6 mesi rileggermi il codice e RICOSTRUIRE dove
intervenire....è una follia!
Va benissimo per "Autocar2000" il sw per gestire l riparazioni di una
officina!
Ma non per "IperCar3000" ch gestisce tutte le officine di una rete
aziendale!
Se hai fatto 3 form i croce ed un modulo....oh beh!....spreco di tempo
ma fa pure!
ma se hai un progetto MEDIAMENTE( non tanto) complesso....follia pura
andare a rileggersi cosa si è fatto 6 esi fà...DAL CODICE!
Anche senza 6 mesi fà: siamo in 3 a sviluppare un sw...ognuno fa la
sua parte...SE TUTTI E 3 dobiamo leggere oa ha scrito UNO DI
NOI....tutte le volte che agiornamo il progetto....se è così...almeno
2 di noi sono ridondanti!
Esiste il programmatore senior o il capo del progetto...lui ha una
cosa fondamentale l'analisi del progetto. Lui distribuisce il
lavoro...controlla l'avanzamento lavoro.
Lui si occupa di controllare che mantegano la documentazione del
programma.
Lui si occupa di manutenere (anche traite persona delegata) il manuale
del programmatore dell'applicazione!
Io mi ricordo 25 anni fa quando mia madre aveva una olivetti ...a
schede magnetiche!
Ci faceva le paghe a molte aziende. Era una specie i mainframe dei
tempi a schede magnetiche.
Il programmatore quando eniva a fare una modifica ...aveva un librone
la "lista delle procedure"....consultav quello per saper DOVE andare a
modificare!
Questo 25 anni fà!
Oggi puoi:
-) fare lo stesso...avere un librone è comodo....lo tieni in ufficio e
lo consulti quando vuoi....al costo di ammazzar qualche albero!
-) Ti affidi a sw specifici...SVN e roba simile...WIKI etc...però devi
avere un pc acceso e un collegamento internet
Io preferisco la buona vecchia carta riciclata!
:o)

 avere un pc acceso e un collegamento internet
Ma guarda, sono del tutto a favore dell'esistenza di un "manuale del 
programmatore".
Bisogna avere un documento che ti dica almeno la parte di programma che 
fa una determinata cosa, altrimenti ci si mette un sacco di tempo solo 
per trovare il punto esatto.
Il fatto di scrivere codice chiaro aiuta molto nel momento in cui sai il 
punto in cui devi intervenire e ti accingi a fare la modifica.
Converrai con me che così è più facile capire cosa sta facendo il 
codice, e a fare la modifica ci metterai molto meno!
No?
-- 
S.

 contorta o poco chiara, o tutte e due.
Non sono del tutto d'accordo, a meno che tu non sia l'unico che
mette le mani su quel codice.
Un pezzo come questo:
                  If .NumeroDX < .NumeroSX Then
                     NumeroPag = Format$(.NumeroDX, "00")
                     Riga = Riga & NumeroPag & "   " & .PagDX & vbTab
                     NumeroPag = Format$(.NumeroSX, "00")
                     Riga = Riga & NumeroPag & "   " & .PagSX
[CUT di venti righe]
                  Else
                     NumeroPag = Format$(.NumeroSX, "00")
                     Riga = Riga & NumeroPag & "   " & .PagDX & vbTab
                     NumeroPag = Format$(.NumeroDX, "00")
                     Riga = Riga & NumeroPag & "   " & .PagSX
[CUT di altre venti righe simili, ma in ordine diverso rispetto alle prime]
                  End If
senza spiegazioni è difficile da comprendere a colpo d'occhio.
E' abbastanza semplice e lineare per la sua funzione, ma rimane
il fatto che devi mentalmente decodificarlo per capire cosa fa.
E per poterlo fare devi sapere a cosa corrispondono le variabili
e cosa fa nel contesto del resto della routine.
[Per chiarire, è un pezzetto di una funzione che costruisce riga
per riga una breve lista dai valori di una matrice di UDT.]
Con due righe di commento, tipo:
  ' La pagina dell'accoppiata che ha il numero più basso va sempre per
  '  prima nella lista, e l'ordine cambia se i più alti sono a destra o sinistra
è molto più comprensibile già al primo sguardo, e se non altro evita,
a chi stia cercando qualcosa, di perdere tempo se non è quello che
gli interessa. O anche a te stesso, il mese dopo averlo scritto :-).
Bye, G. 

Visto il giro di interventi ho capito che non esiste assolutamente una
cosa "fissa" o universale.
Per chiarire un po' quello che mi serve sapere o capire penso di dover
spiegare la mia posizione rispetto al progetto:
Sono un programmatore JUNIOR con poca esperienza (circa 2 anni), sono
referente da 6 mesi di un team di 2 persone (3 se mi comprendo) per un
progetto che ormai va avanti da circa 6 mesi.
Ha circa un centinaio di form, divisi in 13 progetti più o meno
grossi.
Ora, pensavo di fare una cosa del genere:
Volevo fare un documento per ogni classe esterno al codice (con word
ad esempio), intitolato con il nome della classe e per ogni metodo che
la compone sicreverci "COSA" fa ed i parametri che le servono,
potrebbe essere una cosa intelligente?
Un'altra cosa, la documentazione del codice che hanno fatto altre
persone la vorrei fare comunque io (per avvicinarmi a tutto il
progetto) secondo voi è una cosa intelligente oppure glielo faccio
fare a loro?
Grazie per ulteriori interventi che verranno fatti

 Grazie per ulteriori interventi che verranno fatti
Io avevo fatto così ...ed ancora faccio così....
La documentazione è in word...ho fermo li in un cassetto la
trasposizione in access implementata a metà (Access comodissimo
sopratutto perchè alla fine viene fuori UN SOLO file facile da
trasportare in una chiavetta usb!)
Ho come hai detto tu la documentazione della classe o del modulo
Però serve anche : tracciato record
Feedback utente (quello che l'utente dic che non va...o che vorrebbe
l'applicazione facesse)
Lavori preparatori (l'analisi)
Lista todo
lista bug
Lista OCX librerie....di tuta la roba esterna che usi...questa lista è
IMPORTANTISSIMA! SUPER IPER MEGA IMPORTANTE in vb6....lì mi si sono
scottato di brutto!
Ho usato nel passato un ocx di terzi...e sviluppato il progetto anche
su quello!....poi ho formattato dopo 2 anni il pc!
Il cliente dopo 3 anni mi ha chiesto una modifica...a la sw house
aveva chiuso e cmq qull'ocx era stato ABBANDONATO....io non avevo
salvato le librerie...ho dovuto ristrutturare parte dell'applicazione
Quindi SALVA anche le varie dll ocx ....che usi nel tuo progetto!
(parlo del setup e tutto)
ORA
esistono pacchetti che fanno questo in automatico....
SVN credo tenga traccia oltre che delle versioni ANCHE dei documenti
correlati
SourceSafe credo anche
Io non ho MAI usato questi cosi (a dire la verità SVN è da un o che
periodicamente provo ad installarlo ma mi ci scontro come contro un
muro!)....ma dovrò usarli!
Oramai anche io ho un bel po di progetti vecchi e progetti nuovi....e
già comincio ad avere le scatole piene di contribuire alla
deforestazione: ho una libreria piena di scartoffie!
Credo comunque che se siete in 3 a sviluppare....vi volte molto del
male...se non avete anche un sistema di controllo versione!!!
A me è successo più di una volta che Programmatore3 cancellasse il
lavoro di Programmatore1....
a dire la verità è anche successo che
programmatoreWodka....cancellasse in un raptus il lavoro di
ProgrammatoreWodka della settimana prima!!!
:oP

Io tempo fa producevo un po' di documentazione attraverso l'accoppiata 
MZTools e VBDox: con MZTools inserivo intestazioni di routine e/o di modulo 
nelle quali descrivevo, in breve, moduli, classi, routine (con i loro 
parametri), proprieta', ecc.; VBDox, dall'analisi dei sorgenti e dei 
commenti, opportunamente formattati con MZTools, mi generava automaticamente 
la documentazione del software.
Questo metodo aveva il vantaggio di consentirmi di produrre una discreta 
documentazione con poco sforzo. In tal modo, se qualcosa nel software 
cambiava significativamente, l'aggiornamento della documentazione mi costava 
pochissimo tempo: bastava semplicemente dare i miei files di progetto in 
pasto a VBDox e lasciargli rieseguire la generazione della documentazione.
Ciao!
    Alex

 SourceSafe credo anche
Semplici documenti sicuramente.
File binari credo anche, ma ora non ho la possibilità di provare.
Anche perché provo una certa repulsione per SS  ;)
 > Io non ho MAI usato questi cosi (a dire la verità SVN è da un o che
 > periodicamente provo ad installarlo ma mi ci scontro come contro un
 > muro!)....ma dovrò usarli!
Se ti va posso provare ad aiutarti (eventualmente in privato: la mail è 
valida togliendo un po' di underscore qui e là).
 > Oramai anche io ho un bel po di progetti vecchi e progetti nuovi....e
 > già comincio ad avere le scatole piene di contribuire alla
 > deforestazione: ho una libreria piena di scartoffie!
Allora niente di meglio di SNV.
Oddio, qualcosa di migliore ci sarebbe, ma dal punto di vista 
dell'integrazione con Windows rappresenta il miglior compromesso.
Ed è anche semplice da usare.
-- 
S.

 mette le mani su quel codice.
[snip]
Recito il mea culpa (per la parte che ho scritto e che hai quotato qui 
sopra), non mi sono espresso bene.
Quando scrivo "Se ti trovi a dover spiegare il codice di una routine" 
intendo spiegare *come* una routine fa il proprio lavoro.
Nell'esempio che hai fatto tu, viene spiegato *cosa* fa una routine, il 
che è radicalmente diverso e indubbiamente giusto: io sono pienamente a 
favore di un commento nei pressi della dichiarazione della routine che 
dica *cosa* la routine stessa fa.
E' spiegare il *come* che, personalmente, reputo un brutto segno.
Oh, poi non è detto che sia effettivamente tale: magari si sta facendo 
una cosa talmente complicata che è bene documentare i vari passaggi a 
beneficio di chi ci dovrà mettere le mani in futuro.
-- 
S.

 e VBDox
VBDox non lo conoscevo, pare interessante :-). Grazie.
Bye, G. 

 ProgrammatoreWodka della settimana prima!!!
A me è successo in un programma che è stato sdoppiato in due
versioni abbastanza diverse, di rifare per la versione B una routine
che avevo già aggiunto due anni prima alla versione A su richiesta
di un collega, ma me ne ero scordato =:-(
La cosa bella è che avevo un senso di deja-vu, e non capivo il
perché, fino alla fine.
Poi ho ricontrollato e il codice era praticamente identico nelle
due versioni... :-/
Bye, G. 

 fare a loro?
Bella domanda... sicuramente arriveresti a conoscere meglio il
codice, ma altrettanto sicuramente ti troveresti a romprere le
pelotas più volte agli altri chiedendo cosa fa questa o quella routine,
perché ha fatto così anziché cosa...
*Quanto* sono suscettibili questi colleghi ? :-)
Comunque non ho mai programmato in gruppo, quindi passo.
Bye, G. 

 La cosa bella è che avevo un senso di deja-vu
anch'io :P
ho quasi smesso di studiare i linguaggi, perché è molto più istruttivo ed 
efficace studiare i programmatori :) 

 efficace studiare i programmatori :)
In effetti... A (s)proposito, l'hai mandato tu questo link, o lo devo
mandare io, che sto indietro di una vita, lì ?
http://www.wikihow.com/Define-a-Problem
Bye, G. 

 
http://www.wikihow.com/Define-a-Problem
l'hanno mandato altri. io ho solo commentato che
Einstein is quoted as having said that if he had one hour to save the world 
he would spend fifty-five minutes defining the problem and only five minutes 
finding the solution.
che speriamo che non fosse l'ultima ora del mondo, che ci fosse anche un 
61esimo minuto, senň aveva interamente sprecato il suo tempo :) 

Ciao a tutti,
Non ci pestiamo i piedi a vicenda perché utilizziamo SourceSave, mi ci
trovo bene e non mi ha mai dato problemi di gestione del progetto
globale,
gli altri programmi citati non ho mai neanche provato ad installarli,
anzi è la prima volta che li sento.
Cerco di trarre delle conclusioni e vi chiedo se siete d'accordo,
morale della favola, forse la migliore cosa da fare è:
1 - Semplificare il codice con routine MOOOOLTO chiare
2 - Descrivere il codice abbondantemente con commenti
3 - Fare comunque una documentazione riassuntiva su un documento
esterno (classe, metodo, todo, richieste cliente e riferimenti
utilizzati)
4 - Ogni modifica va documentata anche sui riassunti esterni
Spero di aver afferrato il concetto, infatti vorrei proprio fare una
cosa fatta bene, anche perchè penso sia estremamente utile per
l'azienda che chiunque possa prendere in mano il codice prodotto fino
a qui.
Immagino siate d'accordo
babbomarcelo

 ha scritto nel messaggio 
news:da820e49-0873-447c...@v39g2000pro.googlegroups.com...
