Newsgroup: it.comp.lang.visual-basic
Titolo: Sondaggio

Ciao,
questo e' un post un po' anomalo... non chiedo un'aiuto ma
semplicemente sentire le vostre opinioni.
Quanti di voi finiti i lavori creano un manuale tecnico?
Da non confondersi con il manuale utente che ovviamente deve essere
fatto.
Per tecnico intendo un documento con le seguenti caratteristiche:
- spiegazione dettagliata del funzionamento delle varie procedure,
parametri compresi
- diagramma di flusso dell'applicativo
- copia del codice in allegato
- parte descrittiva del funzionamento e varie...
Diciamo che questi sono i punti che mi vengono in mente ma servono
solo per darvi un'idea di cosa ci dovrebbe essere.
Lo fate? Lo trovate utile o preferite (come me) commentare il codice?
Grazie mille per i vostri fedback!
Ciao BlackSun

 - parte descrittiva del funzionamento e varie...
Normalmente no,
ma ovviamente dipende dagli accordi con il committente.
Dare il codice sorgente non � cos� scontato ... anzi.
Tutti gli altri punti dipendono, grosso modo, da quanto detto sopra.
Posto, ad esempio, che il codice venga consegnato, allora:
alcuni chiedono l'UML, altri si accontententano di una relazione pi� o 
meno dettagliata dello schema di funzionamento.
Un progetto fatto con i dovuti crismi dovrebbe contenere tutto ci� che 
hai citato e magari con in pi� un bel GANTT e l'analisi preliminare.
ciao
stefano

 stefano

 Lo fate? Lo trovate utile o preferite (come me) commentare il codice?
Io sui progetti creati da zero, genero un foglio readme che espone le
possibilit� di configurazione ed elaborazione del programma. Classico uso
quando hai un sw su cui metti le mani raramente, in 2 pagine sai in massima
cosa fa, e come settare i parametri per fargli fare una cosa o un'altra.
Poi nelle procedure hai i commenti che chiariscono tutto.
Diverso se si lavora fortemente in Team, probabilmente.

 - parte descrittiva del funzionamento e varie...
noi usiamo in maniera estensiva la sintassi per i commenti xml e poi 
ove necessario Sandcastle per generare la documentazione, ï¿œ un po' un 
macello generare la parte concettuale ma si puï¿œ fare.
I sorgenti li diamo raramente se non esplicitamente concordato e 
pagato.
.m
-- 
Mauro Servienti
{C67C0157-5D98-4733-A75E-93CAEE4BADC8}
Microsoft MVP - Visual C# / MCP
http://mvp.support.microsoft.com
http://blogs.ugidotnet.org/topics
whynot [ at ] topics [ dot ] it

 Diverso se si lavora fortemente in Team, probabilmente.
Se si lavora in 10 e' un conto ma se si e' al massimo in 2 credo che
tra commenti e readme vari non sia impossibile.
Grazie per il feedback
Ciao BlackSun

 Lo fate? Lo trovate utile o preferite (come me) commentare il codice?
Da me, negli ultimi dieci anni, non � che si sia documentato un granch�: fra 
cambiamenti normativi e necessit� di rinnovare e migliorare il software, i 
tempi di sviluppo sono quasi sempre piuttosto stretti. E' un peccato, perch� 
ho la netta impressione che il tempo non utilizzato a documentare ci� che si 
produce lo si perde ugualmente sulla distanza.
Quando lavoravo a Milano, prestato ad una grossa societ�, ricordo che la 
documentazione cresceva con il software: siccome tutto era sviluppato su 
commissione presso il cliente, c'era una fase di analisi molto dettagliata, 
si commentava bene e si documentava ogni cosa.
Oggi Visual Studio .Net (prendendo spunto da javadoc) fornisce un grande 
aiuto nella produzione di documentazione a partire dai commenti presenti nel 
codice.
Ma ricordo che anche per VB6 esisteva qualcosa di analogo:
http://vbdox.sourceforge.net/
Spero di aver risposto in maniera pertinente alla tua domanda.
Ciao!
    Alex

 pagato.
Mi ero dimenticato di dire che il tutto e' a livello interno quindi il
sorgente e' disponibile.
Mi viene anche da pensare una cosa... ok per il sorgente che scrivo io
ma per quello generato automaticamente per i form??
Non oso immaginare il copia e incolla del sorgente scritto da me piu'
quello del designer e company... vengono fuori una marea di pagine,
per poi cosa?
Grazie del feedback
Ciao BlackSun

 per poi cosa?
non ho capito.


Noi abbiamo una gestione ibrida che ha portato sinora dei buoni vantaggi.
Nel repository SVN vengono documentate tutte le modifiche effettuate,
possibilmente con descrizioni dettagliate del
problema/aggiornamento/aggiunta nuova funzione.
A questo si aggiunge che il repository SVN � collegato ad un sistema di
bugtracking, nel quale vengono inseriti bug, miglioramenti, nuove
funzionalit�.
Infine quasi ogni modulo a corredo del nostro software (che � fortemente
modulare) viene documentato su quali sono i parametri di configurazione,
i file config necessari, le tabelle richieste nel db ecc...
Il codice � spesso mal commentato (o a volte per nulla commentato),
retaggio di precedenti programmatori. Oggi, come regola, tutto il codice
deve essere commentato man mano che lo si crea\modifica.
Gli svantaggi di questo approccio sono che a volte le varie informazioni
contrastano tra loro (soprattutto quando per pigrizia qualcuno non
aggiorna correttamente i documenti), a volte sembra un p� macchinoso il
fatto di dover scrivere 10 righe di commenti nell'SVN e\o sul codice,
per aver magari eliminato 2 righe di codice.
Il vantaggio principale � di avere una documentazione tecnica aggiornata
che chiunque pu� capire senza sbatterci troppo la testa.
Il tutto coadiuvato dal fatto che in SVN, leggendo i log, puoi capire
come il software si � evoluto nel tempo (cosa molto utile in caso di
regressioni o malfunzionamenti).
Nicola

 Spero di aver risposto in maniera pertinente alla tua domanda.
Si e' vero che avere un bel manuale tecnico, completo ed esaustivo
sarebbe una figata enorme come mi trovi d'accordo su progetti molto
complessi ma il tempo a volte non te lo permette e anche il progetto
stesso non presenta particolari motivi per tener traccia di tutto cio'
che si e' fatto.
Credo che molto dipenda dalla complessita' del progetto, piu' e'
mastodontico piu' la documentazione e' necessaria (chissa' quanta ce
ne sara' per un programma come Excel eheheh), ma per medi/piccoli non
lo vedo adatto... o meglio il tempo che gli si dedicherebbe sarebbe
troppo per il tipo di lavoro.
Grazie per il feedback :-)
Sempre piacevole confrontarsi su queste cose :-)
Ciak BlackSun

 non ho capito.
Si scusa mi perdo dei pezzi... in pratica per codice viene inteso
anche quello contenuto nel file XXX.Designer.vb.
La persona che si sta inventando questo metodo vorrebbe che facendo un
copia/incolla del codice riportato nel manuale, il programma funzioni.
Io mi sono astenuto da qualsiasi commento... :-D ho solo sorriso e ho
domandato: "Ne sei certo?"... risposta sua perentoria: "Si
assolutamente"
Ciao BlackSun

 assolutamente"
A parte che, come dicevi, la cosa fa ridere...
Ma questo tizio conosce i sistemi di versioning?
Subversion costa zero (� open source) e fa esattamente ci� che gli serve.
Nicola

 Subversion costa zero (è open source) e fa esattamente ciò che gli serve.
ahhahahah ma va...giusto 2 cose per farti capire il livello...
- quando siamo passati a VB2005 e XP come S.O. gli dissi che avrebbe
dovuto installare il FX su tutte le macchine client... la sua domanda
fu: "Ma e' proprio necessario?? Non funziona senza?"
- ora sta "insegnando" a un altro collega a programmare... in azienda
io uso VB2008... lui gli sta insegnando... VB6.
Mi domando l'utilita' ... parti subito con .Net no?? Il motivo e'
semplice... lui conosce solo VB6. Niente da dire su chi usa ancora VB6
ma non si deve spacciare per uno che e' all'avanguardia.
Ciao BlackSun

 infatti non le seguo :-)
Mi spiace per te. Io scoppierei in un ambiente di lavoro cos�.
Fortunatamente, ho solo colleghi ben preparati.
Nicola

 Fortunatamente, ho solo colleghi ben preparati.
Si sei fortunato. Io invece sono l'unico programmatore quindi non ho
modelli dal quale imparare.
Finora mi sono destreggiato con Google, il NG dove ci sono persone
pronte a dare una mano (grazie!!) e alcuni libri.
Ciao BlackSun

 wrote:
Nella fase ideativa casa è piena di fogli scritti a mano!
"Casa" perchè le pensate migliori si fanno in due posti:
-) Seduti sul vaso (traduco in italiano: seduti sul cesso)
-) La notte
Una volta fatto tutto
....tengo stampata la struttura del database.
....ed una scaletta di "cose da fare" (ToDo List)
Il codice lo commento ogni tanto...cerco invece di fare uno sforzo
sulle variabili e dargli dei nomi significativi anche se vuol dire
scrivere di più!
In rari casi tengo scritto qualcosa.
Quello che invece tengo scritto e custodisco come una reliquia è la
lista di tutto quello che ho cambiato all'applicazione base per
soddisfare lo stramaledetto uTonto!
I problemi nascono non nel rimettere mano all'applicazione
"pura"....ma da quelle sporcate dalle ignominiose richieste
dell'uTonto.....il famoso form rosa!

 scrivere di pi�!
Secondo me l'intellisense di vs2010 in questo senso aiuta e non poco, non
hai pi� problemi a ricordarti una propriet� es. BackColorOnFocus oppure
OnFocusBackcolor, stessa cosa per le variabili.