Esiste uno standard per documentare l'architettura di alto livello di un programma?

10

Sono uno sviluppatore dilettante e tutti i miei programmi fino ad ora erano abbastanza semplici da essere documentati all'interno del codice. Durante la lettura del codice era chiaro cosa stavo facendo una tale azione (il mio test standard era guardare il codice 6 mesi dopo e capire tutto alla prima lettura - e ho una breve durata della memoria).

Ora mi trovo di fronte a un programma che sta superando le mie capacità per ricordare le varie interazioni tra

  • il codice stesso
  • gli indici nel database
  • le interazioni tra i vari moduli (codice principale "lavoratore" e "libreria")

La mia documentazione attuale è una lavagna in cui ho tutti i tipi di caselle e frecce che puntano al codice, agli indici del database, alle azioni eseguite, al cambio di stato ecc. Solo per riferimento, un frammento del pasticcio:

Lamiadomandaèseesisteunaseriestandardodenominatadibestpractice(denominatanelsensochesitrattadiuninsiemedipraticheraggruppatesottounnomespecifico)perladocumentazionediprodottipiùcomplessi.

Qualisonoleparolechiavechedovreicercare(itentativigeneralidi"standard di architettura del software per i documenti" e simili variazioni di solito portano a software per i flussi di lavoro o alla costruzione di sistemi CAD di architettura).

Mi aspetto anche che non ci possano essere best practice generali per le descrizioni di alto livello e che ognuno costruisca una propria filosofia.

    
posta WoJ 25.04.2017 - 12:26
fonte

4 risposte

13

Non esiste uno standard a cui tutti aderiscano. I progetti software possono variare notevolmente (si pensi a: helloworld.py vs il codice nello space shuttle).

Un metodo molto comune è utilizzare il 4 + 1 modello . Invece di provare a racchiudere tutto in un unico stile di documento, questa metodologia interrompe il progetto in cinque componenti:

  • La Development vista
  • La vista logica
  • La vista fisica
  • La procedura vista
  • Scenari

Le varie viste descrivono il prodotto da quattro diverse prospettive. Gli scenari sono dove vivono i casi d'uso e descrivono l'interazione delle altre viste.

Nota: questo è un modello concettuale e non è legato ad alcuno strumento specifico.

Puoi leggere di più qui:

  1. 4 + 1 modello di visualizzazione architettonica (wikipedia)
  2. Progetti architettonici: il modello di architettura del software "4 + 1" (Documento IEEE - pdf)
risposta data 25.04.2017 - 18:10
fonte
3

IMHO UML è non uno strumento che funziona bene per documentare l'architettura del software del mondo reale. I diagrammi delle classi sono utili, ma usano un livello di astrazione che è spesso troppo basso per questo scopo. I diagrammi dei casi d'uso sono in genere troppo "di alto livello" e mancano certi aspetti. Altri tipi di diagrammi UML hanno problemi simili (per essere giusti, i diagrammi dei pacchetti, i diagrammi di implementazione, i diagrammi dei componenti possono documentare alcuni aspetti architettonici, ma personalmente non li ho mai trovati molto utili).

Se stai cercando un metodo funzionante, pragmatico per documentare architetture di alto livello, ti suggerisco di familiarizzare con diagrammi di flusso di dati . Questi sono facili da capire e hanno il vantaggio che possono scalare a diversi livelli di astrazione. Li ho trovati più utili per documentare diversi tipi di sistemi. Peccato che non abbiano trovato il modo in UML, ma comunque ci sono molti strumenti, anche gratuiti come Dia o DrawIO - per fare questi diagrammi.

Come nota a margine, perché hai bisogno di "indici nel database" in una documentazione di alto livello? Penso che siano un dettaglio di implementazione del tuo modello di dati (relazionale?), E se li aggiungi o meno è - per la mia esperienza - più una questione di prestazioni e ottimizzazione.

    
risposta data 27.04.2017 - 13:10
fonte
0

L'UML (Unified Modeling Language) è un linguaggio di modellazione di scopo generale, di sviluppo nel campo dell'ingegneria del software, inteso a fornire un modo standard per visualizzare il progetto di un sistema.

    
risposta data 25.04.2017 - 13:17
fonte
-3

Penso che siamo abituati a fare meglio. UML sembrava buttare fuori il bambino con l'acqua del bagno. Fornendo un linguaggio di modellazione unificato ha abolito la distinzione tra architettura e implementazione. O se non avesse intenzione di farlo sembrava essere efficace.

Ho visto alcuni modelli UML di mostri e francamente non fanno nulla per me che il codice non potrebbe fare, e lo fanno meglio.

    
risposta data 25.04.2017 - 14:51
fonte

Leggi altre domande sui tag