Se stai documentando un progetto o un'architettura di un sistema che è già stato costruito, il documento dovrebbe descriverlo come costruito e non come progettato o come previsto. Se ci sono stranezze o discrepanze nell'architettura, allora questo documento dovrebbe richiamare quei problemi e spiegarli il più possibile a un lettore.

Se sei in grado di ottenere informazioni da persone che hanno lavorato al sistema fin dall'inizio (o almeno più a lungo di te), sarebbe utile acquisire maggiori informazioni su ciò che era effettivamente inteso e sul perché l'architettura e il design deviato da questa intenzione.

Alla fine della giornata, un documento di progettazione dovrebbe servire da guida per il codice. Se il documento non aiuta un nuovo sviluppatore a capire lo stato corrente del codice base e come è strutturato, il documento non è utile.

Questo documento dovrebbe essere un documento vivente che viene utilizzato per guidare la pianificazione e la progettazione future delle modifiche al sistema e quindi aggiornato di conseguenza, all'interno del processo di sviluppo. Poiché il design cambia e si evolve nel tempo, il documento dovrebbe anche aiutare gli sviluppatori a capire perché le cose sono come sono al momento.

Se stai cercando consigli su come catturare l'architettura, mi piace l'approccio sostenuto in IEEE Standard 1016- 2009 Standard IEEE per Information Technology - Systems Design - Descrizione del design del software . Fornisce una struttura ragionevole per una descrizione del progetto, che può essere utilizzata per acquisire informazioni di progettazione a livello di architettura e di dettaglio.

Vorrei anche considerare queste deviazioni come una forma di debito tecnico. Potrebbe essere una grande impresa, forse anche un piccolo progetto, per risolvere i problemi, raccomanderei di rendere più visibile l'esistenza del debito tecnico. Se ciò significa che usi lo strumento di tracciamento dei difetti, puoi inserire uno o più problemi lì. Se hai un altro strumento che utilizzi per rintracciare suggerimenti e miglioramenti al software, potrebbe essere un altro posto in cui metterlo.

Quando formalizzi l'architettura del sistema, è importante capire non solo il valore che sta dietro l'architettura, ma anche capire e apprezzare ciò che dovrebbe essere.

Gli obiettivi principali dell'architettura software o tecnica sono identificare i requisiti non funzionali realizzati dal Attributi di qualità che guideranno Architettura di sistema .

Requisiti non funzionali:

A non-functional requirement is a requirement that specifies criteria that can be used to judge the operation of a system, rather than specific behaviors. They are contrasted with functional requirements that define specific behavior or functions. The plan for implementing functional requirements is detailed in the system design. The plan for implementing non-functional requirements is detailed in the system architecture.

Broadly, functional requirements define what a system is supposed to do and non-functional requirements define how a system is supposed to be. ... Non-functional requirements are often called "quality attributes" of a system. Other terms for non-functional requirements are "qualities", "quality goals", "quality of service requirements", "constraints" and "non-behavioral requirements"

Naturalmente identificare i requisiti architettonicamente significativi ha senso quando si lavora su un progetto greenfield, tuttavia quando si lavora con software esistenti, è meglio essere il più disciplinati possibile. Non vorrai che la tua architettura software sia influenzata dal sistema esistente.

L'architettura del software per essere autorevole ha davvero bisogno di essere 3 cose.

dichiarativa

Questa è la parte della documentazione in cui dichiari NOT WHAT IS, ma come dovrebbero essere le cose. Lo facciamo attraverso l'uso di varie viste architettoniche del sistema. Definiamo i componenti che dovrebbero essere, il modo in cui interagiscono e quindi eseguiamo il drill-down facoltativo in ogni componente per ottenere visualizzazioni più granulari che dichiarino come deve essere progettato il sistema.

Questa è una distinzione importante. Il System Design dovrebbe essere vincolato dall'architettura di sistema, sono in effetti cose separate ma correlate.

Motivazioni

La logica dell'architettura del software è ciò che fornisce legittimità e autorità alle decisioni sull'architettura che sono state prese. Forse è stata presa la decisione di utilizzare un listener di eventi Pub / Sub su MQ per l'attivazione di un lavoro batch e lo si disegna?

Perché è stata presa questa decisione? Spieghiamo perché nella sezione Rationale e colleghiamo la nostra spiegazione ai requisiti non funzionali, agli obiettivi degli attributi di qualità o ai requisiti significativi dal punto di vista dell'architettura. Ad esempio, i lavori devono essere asincroni e ripetibili, la manutenibilità come attributo di qualità determina che in caso di un errore del processo batch i lavori possono essere riavviati tramite un messaggio MQ, il sistema deve avere una perdita di messaggi zero con comunicazione asincrona, ecc. ..)

Rischi

Ora che hai dichiarato come dovrebbe essere l'architettura e lo hai dimostrato con il tuo Razionale, ora puoi identificare Rischi sullo stato corrente del sistema dove non è rispettato.

(Ad esempio, la convalida lato server viene duplicata sul codice Javascript lato client. Si tratta di una violazione del principio DRY e ciò contrasta con l'attributo di qualità di manutenibilità.Non ci sono requisiti non funzionali definiti intorno alle prestazioni in questo area quindi non esiste una logica per il comportamento attuale del sistema)

I tuoi rischi possono anche rappresentare il diagramma in cui lo stato corrente sta attualmente scostandosi dall'architettura. Questi rischi possono essere affrontati dal team di sviluppo ora, sia attraverso il loro piano di progetto o aggiungendo questo nel backlog.

Devi davvero decidere se devi documentare la struttura corrente del progetto, o la struttura desiderata del progetto, o entrambi.

Potresti documentare l'obiettivo, allo scopo di guidare lo sviluppo futuro lungo le linee desiderate, e aumentare le deviazioni come bug (forse il link a questi bug dalle parti rilevanti del documento). Oppure puoi documentare la realtà per fornire un'introduzione / una panoramica del codice. Oppure puoi documentare entrambi i side-by-side, in modo da avere contemporaneamente una guida per lo sviluppo futuro e una descrizione accurata del codice corrente in un unico punto. Tutti sono ragionevoli a seconda di cosa dovrebbe essere il documento, quindi non penso che possiamo indicarti quale dei due è utile.

Dovresti anche ricordare che l'architettura desiderata potrebbe non essere universalmente condivisa tra coloro che sono coinvolti (o perché vogliono cose diverse, o perché alcuni di loro hanno capito che alcuni desideri condivisi originali erano impossibili o impraticabile e quindi è ricorso a scrivere il codice esistente che devia dall'obiettivo). Quindi devi anche sapere se hai o meno l'autorità di decidere cosa è desiderato, e se non chi lo fa. La struttura esistente ha almeno il pregio che ce ne sia solo una da documentare!

Scrivi nel documento di progettazione dell'architettura cosa dovrebbe essere, e per ogni conflitto trovi un ticket nel bug tracker che descrive il conflitto. La sezione commenti del ticket offrirà una piattaforma per le persone interessate per discutere di quel particolare conflitto.

Si noti che la risoluzione di ciascuno di questi ticket può essere quella di modificare l'implementazione in modo che corrisponda al design, ma può anche essere quella di modificare il progetto in modo che corrisponda all'implementazione. Idealmente il primo è preferito, ma a volte ci sono vincoli tecnici e / o commerciali che lo rendono più efficiente / pragmatico / possibile scegliere il successivo. In tal caso, potrebbe essere una buona idea fare riferimento al ticket dal documento di progettazione dell'architettura, in modo che i futuri lettori che non capiscono perché è stata scelta quella particolare scelta di design inferiore possono leggere la discussione nel ticket e comprendere il ragionamento alla base esso.

Sarei propenso a scrivere un documento architettonico organizzato in 3 sezioni principali.

Il primo a introdurre il design / architettura inizialmente previsto. Ciò consentirà ai nuovi sviluppatori / lettori di farsi un'idea per ciò che il sistema dovrebbe fare e dovrebbe ovviamente essere legato ai requisiti / agli impieghi ecc.

La seconda sezione dovrebbe spiegare molto chiaramente cosa sia l'architettura in realtà . Ciò consente ai nuovi sviluppatori / lettori di farsi un'idea dello stato attuale e di cosa hanno a che fare se guardano il software (e potenzialmente altra documentazione). Questa sezione dovrebbe indicare chiaramente la differenza tra ciò che è stato inteso e la realtà, poiché molto probabilmente illuminerà le cose che sono molto sbagliate con l'architettura originale (si spera non siano troppe!) e aree in cui le scorciatoie / gli hack (probabilmente un po 'pochi se c'è stata una grande pressione sul team di sviluppo) sono stati fatti e i requisiti non sono stati soddisfatti o il software sta iniziando a sembrare "scarsamente" progettati cioè fragili, instabili, non -portatile.

Infine, penso che una sezione che dettaglia le raccomandazioni su cosa deve accadere ora. Questo dovrebbe essere qualsiasi modifica all'architettura / design e una tabella di marcia per le modifiche al software al momento, al fine di rendere la vostra visione diventare una realtà.

Penso che questo copra (ad alto livello) ciò che deve essere catturato. Il modo in cui lo fai in termini di sottosezioni del documento o del software di tracciamento dei bug che utilizzi dipende dal dominio in cui lavori / preferenza personale / dimensione della squadra / budget / scala temporale ecc.