Come includere correttamente la convalida del campo in una documentazione del software

4

Sto sviluppando una documentazione software in un progetto, e molte di esse sono solo funzioni basate su CRUD o CRUD. Come puoi immaginare, molte regole sono vincoli sulla convalida dei campi, cose come la lunghezza, l'intervallo, il tipo di dati e le maschere del campo.

Scrivere tutte quelle regole sarebbe scomodo da scrivere e da leggere, quindi mi chiedo, quali sono le opzioni disponibili per includere tali regole in una documentazione software, in modo che non sia noioso scriverlo / leggerlo tutto ?

Modifica - Chiarimento

Le regole e vengono prese da una vecchia applicazione legacy desktop, e stiamo andando a documentare le convalide, le caratteristiche e le forme attuali; quindi l'applicazione verrà implementata in una piattaforma più aggiornata (web), considerando l'usabilità e la coerenza nel nuovo sistema. La documentazione è scritta a mano utilizzando lo strumento Sybase PowerDesigner , ma il documento può essere scritto in doc all'interno dello strumento.

Alcuni di questi sono regole di convalida a campi incrociati, per esempio;

  • Per una persona di tipo X, residente nel paese Y, il valore del campo A deve essere convalidato utilizzando la regola B.
  • Per una persona di tipo X, residente nel paese Z, il valore del campo A deve essere convalidato utilizzando la regola C e il campo D, convalidato tramite la regola E.

Il tipo X, il paese Y, il campo A, il campo D, ecc., sono tutti valori estratti dai campi sui moduli.

    
posta RMalke 26.12.2012 - 13:17
fonte

2 risposte

2

Il modo migliore per rendere leggibile questo è mantenere il layout di questi requisiti coerente in Doc.

Penso che sia più importante il formato stesso, che direi che userei una griglia di base. Se non è necessario alcun valore, lascia vuoto. (al contrario di scrivere Nessuno)

La prima colonna è Proprietà archiviata, la colonna 2 è quel valore (o descrizione).

Name                Email
Type                Text
Length              150
FK Constraint          
Other Validation    Standard Email Validation 
    
risposta data 26.12.2012 - 14:14
fonte
1

Quindi hai a portata di mano una vecchia applicazione legacy che contiene già tutte le regole che stai per documentare, e stai cercando un modo per "estrarre" alcune delle regole da esso, senza scriverle manualmente.

In realtà, se ciò è possibile dipende completamente dalla tecnologia e dall'architettura di quell'applicazione. Non ci hai detto nulla su queste cose, quindi posso darti solo un consiglio molto generale.

Il fattore chiave qui è quanti metadati contengono le fonti del vecchio sistema legacy. Con "meta data" intendo qualsiasi tipo di informazione leggibile dalla macchina e auto-descrittiva. Se ci sono alcuni metadati, puoi usarli come input per qualche tipo di generatore di documenti che dovrai scrivere.

Ad esempio, se l'applicazione legacy è basata su database, c'è un buon punto di partenza. Quasi tutti i database seriali consentono l'estrazione di nomi di tabelle, nomi di attributi, tipi di dati degli attributi, vincoli di db, ecc. In modo programmatico. Quindi puoi scrivere tu stesso un programma che estrae quelle informazioni dal DB, o usi le capacità di reverse engineering di PowerDesigner che ti permettono di generare un modello ER completo in pochi minuti.

Se l'applicazione non è basata su database o se le regole di convalida non sono implementate come vincoli di database, l'attività è in genere sempre più difficile. La vecchia tecnologia utilizzata consente di determinare quali moduli sono disponibili? Permette di estrarre quali attributi sono presenti in ogni modulo e c'era un modo standard per aggiungere le regole di convalida in base alla configurazione anziché alla codifica? Impara abbastanza sulla vecchia tecnologia per rispondere a quel tipo di domande. Quindi potresti avere la possibilità di salvare alcuni lavori di documentazione manuale.

Tuttavia, le caratteristiche e le regole di convalida della vecchia applicazione legacy che sono sepolte in una pila di codice scritto a mano non possono quasi mai essere estratte automaticamente. Non aspettarti alcun "mirino magico" per risolvere questo problema per te - non ce n'è, questa parte dei documenti dovrai scrivere manualmente. Scopri le regole leggendo i documenti esistenti della vecchia applicazione, leggendo / eseguendo il debug del codice sorgente di tale applicazione o provando e utilizzando l'applicazione.

EDIT: hai chiesto un modo per evitare lavori di scrittura noiosi e una lettura noiosa. La mia risposta sopra è stata come evitare noiosi scrivere . E credo che la lettura di tali regole di validazione sarà sempre un po 'noiosa, indipendentemente dalla forma che scegli.

Tuttavia, se non sono disponibili metadati esistenti, potrebbe essere una buona idea creare tali metadati durante il processo di documentazione, ad esempio, all'interno dei modelli di PowerDesigner. PowerDesigner è uno strumento in cui AFAIK è possibile memorizzare tutti i dati del modello in un repository centrale. A causa del manuale, ha capacità di scripting (sembra avere un'API COM a cui è possibile accedere da qualsiasi linguaggio di programmazione COM esterno) e potrebbe anche essere possibile estendere il modello meta di PowerDesigner alle proprie esigenze. Quindi, invece di scrivere tutte le regole di convalida in documenti separati in forma verbale, impara abbastanza sul tuo strumento PowerDesigner che puoi memorizzare tali informazioni in un modulo leggibile da una macchina. Quindi sviluppa un generatore di documenti utilizzando le funzionalità di script inbuild o l'API COM.

In questo modo, è possibile mantenere la fonte della documentazione molto compatta, senza molta ridondanza. I documenti generati avranno un layout coerente al 100% e, se necessario, possono essere facilmente personalizzati per scopi diversi. Se ai "lettori" dei documenti non piace il modulo, cambia il generatore e rigenera nuovamente i documenti.

Naturalmente, questo sforzo paga solo per le applicazioni di una certa dimensione. Ho fatto qualcosa di simile in passato per due diversi strumenti CASE, e in realtà è più facile di quanto possa sembrare a prima vista.

    
risposta data 27.12.2012 - 11:15
fonte

Leggi altre domande sui tag