Ho aderito alla metà di un progetto di medie dimensioni, che dura già da diversi anni. Uno dei problemi è che il documento che descrive l'architettura non è mai stato scritto. Ora mi è stato assegnato un compito per scrivere la descrizione dell'architettura.

Durante il periodo in cui ho lavorato a questo progetto, ho raccolto tutte le informazioni necessarie per scrivere il documento. Da quando ho anche aggiunto alcune funzionalità, ho identificato alcune parti di codice, che stanno chiaramente rompendo l'architettura come viene descritta.

Ad esempio, la GUI doveva essere un livello sottile, senza logica aziendale. Questo è quello che mi è stato detto. L'implementazione contiene molta logica.

Il mio capo mi ha assegnato il compito di scrivere il documento che descrive l'architettura del sistema. Il pubblico target sono gli sviluppatori attuali e futuri che lavorano al progetto. Devo descrivere cosa dovrebbe essere, ma devo anche descrivere le deviazioni in qualche modo.

Quindi, dove dovrei descrivere questi problemi? Software di tracciamento dei bug? O dovrei descrivere le deviazioni dell'implementazione dall'architettura nel documento che descrive l'architettura del sistema?

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

Se sei in grado di ottenere informazioni da persone che hanno lavorato sul sistema sin dall'inizio (o almeno più a lungo di quello che hai), sarebbe utile acquisire più informazioni su ciò che era effettivamente previsto e perché l'architettura e il design si sono discostati da questo Intenzione.

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

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

Se stai cercando consigli su come catturare l'architettura, mi piace l'approccio sostenuto dallo standard IEEE 1016-2009 Standard IEEE per la tecnologia dell'informazione - Progettazione dei sistemi - Descrizione del design del software . Fornisce una struttura ragionevole per una descrizione del progetto, che può essere utilizzata per acquisire informazioni di progettazione sia a livello architettonico che 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 il tuo strumento di localizzazione dei difetti, puoi inserire uno o più problemi lì. Se hai un altro strumento che utilizzi per tracciare suggerimenti e miglioramenti al software, potrebbe essere un altro posto dove metterlo.

Quando si formalizza l'architettura del sistema è importante comprendere non solo il valore dietro ciò che l'architettura porterà sul tavolo, ma anche capire e apprezzare ciò che dovrebbe essere.

L'obiettivo primario del software o dell'architettura tecnica è quello di identificare i requisiti non funzionali che vengono realizzati dagli attributi di qualità che guideranno l' architettura di sistema .

Sui requisiti non funzionali:

Un requisito non funzionale è un requisito che specifica i criteri che possono essere utilizzati per giudicare il funzionamento di un sistema, piuttosto che comportamenti specifici. Sono in contrasto con i requisiti funzionali che definiscono comportamenti o funzioni specifici. Il piano per l'implementazione dei requisiti funzionali è dettagliato nella progettazione del sistema. Il piano per l'implementazione di requisiti non funzionali è dettagliato nell'architettura del sistema.

In linea di massima, i requisiti funzionali definiscono cosa dovrebbe fare un sistema e i requisiti non funzionali definiscono come dovrebbe essere un sistema. ... I requisiti non funzionali sono spesso chiamati "attributi di qualità" di un sistema. Altri termini per requisiti non funzionali sono "qualità", "obiettivi di qualità", "requisiti di qualità del servizio", "vincoli" e "requisiti non comportamentali"

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

L'architettura software per essere autorevole deve davvero essere 3 cose.

Dichiarativo

Questa è la parte della documentazione in cui dichiari NON CHE COSA È, ma come DOVREBBE ESSERE. Lo facciamo attraverso l'uso di varie viste architettoniche del sistema. Definiamo i componenti che dovrebbero essere, il modo in cui interagiscono e quindi facoltativamente eseguiamo il drill down in ciascun componente per viste più granulari che dichiarano come dovrebbe essere progettato il sistema.

Questa è una distinzione importante. La progettazione del sistema dovrebbe essere limitata dall'architettura del sistema, in realtà sono cose separate ma correlate.

Fondamento logico

La logica della tua architettura 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 aver avviato un processo batch e lo hai disegnato?

Perché è stata presa questa decisione? Spieghiamo perché nella sezione Rationale e ricolleghiamo la nostra spiegazione a Requisiti non funzionali, Obiettivi degli attributi di qualità o Requisiti significativi dal punto di vista architettonico. (Ad esempio, i lavori devono essere asincroni e ripetibili, la manutenibilità come attributo di qualità determina che, in caso di errore di un lavoro 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 l'hai provata con la tua logica, ora puoi identificare i rischi sullo stato attuale del sistema in cui questo non si attesta.

(Ad esempio, la convalida lato server viene duplicata sul codice Javascript lato client. Questa è una violazione del principio DRY e questo è in contrasto con l'attributo di qualità di manutenibilità. Non ci sono requisiti non funzionali definiti attorno alle prestazioni in quest'area quindi non è una motivazione per l'attuale comportamento del sistema)

I rischi possono anche rappresentare lo stato in cui lo stato corrente si sta attualmente discostando dall'architettura. Questi rischi possono essere affrontati dal team di sviluppo ora, attraverso il loro piano di progetto o aggiungendolo nel backlog.

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

È possibile documentare l'obiettivo, allo scopo di guidare lo sviluppo futuro lungo le linee desiderate e aumentare le deviazioni come bug (forse collegare a questi bug dalle parti pertinenti del documento). Oppure potresti documentare la realtà per fornire un'introduzione / una panoramica del codice. Oppure potresti documentare entrambi fianco a fianco, in modo da avere contemporaneamente una guida per lo sviluppo futuro e una descrizione accurata del codice corrente in un unico posto. Tutti sono ragionevoli a seconda di cosa dovrebbe essere previsto per il documento, quindi non credo che possiamo dirti utilmente quale fare.

Dovresti anche tenere presente che l' architettura desiderata potrebbe non essere universalmente concordata tra le persone coinvolte (o perché vogliono cose diverse o perché alcuni di loro hanno capito che alcuni desideri condivisi originali erano impossibili o impraticabili e quindi ricorrevano alla scrittura del codice esistente che si discosta dall'obiettivo). Quindi devi anche sapere se hai o meno l'autorità per decidere cosa desideri e, in caso contrario, chi lo fa. La struttura esistente ha almeno la virtù che ce n'è solo una da documentare!

Scrivi nel documento di progettazione dell'architettura quello che doveva essere, e per ogni conflitto trovi aperto un ticket nel tracker dei bug che descrive il conflitto. La sezione dei commenti del biglietto 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 cambiare l'implementazione in modo che corrisponda al design, ma può anche essere quella di cambiare il design in modo che corrisponda all'implementazione. Idealmente il primo è preferito, ma a volte ci sono vincoli tecnici e / o commerciali che rendono più efficiente / pragmatico / possibile scegliere il successivo. In tal caso, potrebbe essere una buona idea fare riferimento al ticket del documento di progettazione dell'architettura, in modo che i futuri lettori che non capiscono perché sia ​​stata scelta quella particolare scelta di design inferiore possano leggere la discussione nel ticket e comprendere il ragionamento alla base esso.

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

Il primo a presentare il design / l'architettura inizialmente previsti. Ciò consentirà ai nuovi sviluppatori / lettori di farsi un'idea di ciò che il sistema dovrebbe fare e dovrebbe ovviamente essere legato ai requisiti / ai casi d'uso ecc.

La seconda sezione dovrebbe spiegare in modo molto chiaro cosa sia realmente l'architettura . Ciò consente ai nuovi sviluppatori / lettori di farsi un'idea dello stato attuale e di cosa stanno trattando se guardano il software (e potenzialmente altra documentazione). Questa sezione dovrebbe indicare chiaramente la differenza tra ciò che era previsto e la realtà in quanto molto probabilmente metterà in evidenza cose che sono molto sbagliate nell'architettura originale (si spera non troppe!) E aree in cui scorciatoie / hack (probabilmente poche se ce ne fosse un grande grado di pressione sul team di sviluppo) e non sono stati rispettati i requisiti o il software sta iniziando a sembrare "mal progettato", ovvero fragile, instabile, non portatile.

Infine, penso a una sezione che descriva in dettaglio le raccomandazioni per ciò che deve accadere ora. Dovrebbero esserci delle modifiche all'architettura / al design e una tabella di marcia per le modifiche al software al fine di rendere la tua visione 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 impieghi dipende dal dominio in cui stai lavorando / preferenza personale / dimensione del team / budget / scala temporale ecc.