Talin

Follow

3 gennaio, 2019 – 7 min read

Un’abilità importante per qualsiasi ingegnere del software è scrivere i documenti di progettazione tecnica (TDD), chiamati anche documenti di progettazione tecnica (EDD). Qui in questo articolo offro alcuni consigli per scrivere buoni documenti di progettazione e quali errori evitare.

Un avvertimento: team diversi avranno diversi standard e convenzioni per la progettazione tecnica. Non c’è uno standard a livello industriale per il processo di design, né potrebbe esserci, dato che diversi team di sviluppo avranno esigenze diverse a seconda della loro situazione. Quella che descriverò è una possibile risposta, basata sulla mia esperienza personale.

Iniziamo con le basi: Cos’è un documento di progettazione tecnica, e come si inserisce nel processo di progettazione?

Un documento di progettazione tecnica descrive una soluzione ad un dato problema tecnico. È una specifica, o “progetto”, per un programma software o una caratteristica.

La funzione primaria di un TDD è quella di comunicare i dettagli tecnici del lavoro da fare ai membri del team. Tuttavia, c’è un secondo scopo che è altrettanto importante: il processo di scrittura del TDD ti costringe ad organizzare i tuoi pensieri e a considerare ogni aspetto del progetto, assicurandoti di non aver tralasciato nulla.

I documenti di progettazione tecnica sono spesso parte di un processo più ampio che tipicamente ha i seguenti passi:

1. I requisiti del prodotto sono definiti. Questi saranno tipicamente rappresentati da un documento di requisiti di prodotto (PRD). Il PRD specifica ciò che il sistema deve fare, dalla prospettiva di un utente o di un agente esterno.
2. Vengono definiti i requisiti tecnici. I requisiti di prodotto sono tradotti in requisiti tecnici – ciò che il sistema deve fare, ma ora come lo fa. L’output di questo passo è un documento di requisiti tecnici (TRD).
3. Disegno tecnico. Questo contiene una descrizione tecnica della soluzione ai requisiti delineati nei passi precedenti. Il TDD è l’output di questo passo.
4. Implementazione. Questa è la fase in cui la soluzione viene effettivamente costruita.
5. Test. Il sistema viene testato rispetto al PRD e al TRD per assicurare che soddisfi effettivamente i requisiti specificati.

Tra ciascuna di queste fasi c’è tipicamente un processo di revisione per assicurare che non siano stati fatti errori. Se vengono rilevati errori, malintesi o ambiguità, questi devono essere corretti prima di procedere alla fase successiva.

Questo processo è altamente variabile; l’insieme delle fasi elencate qui cambierà caso per caso. Per esempio:

• Per le caratteristiche più piccole che non comportano molta complessità, i passi 2 e 3 saranno spesso combinati in un singolo documento.
• Se la caratteristica comporta un gran numero di incognite o un certo livello di ricerca, può essere necessario costruire un’implementazione proof-of-concept prima di finalizzare il progetto tecnico.

Questo processo avviene anche a diverse scale e livelli di granularità. Un PRD / TRD / TDD può riguardare la progettazione di un intero sistema, o solo una singola caratteristica. Nella maggior parte degli ambienti, il processo è anche ciclico – ogni ciclo di progettazione/implementazione si basa sul lavoro del precedente.

La linea di demarcazione tra TRD e TDD può essere un po’ sfocata a volte. Per esempio, supponiamo che stiate sviluppando un server che comunica tramite un’API RESTful. Se l’obiettivo è quello di conformarsi ad un’API già stabilita e documentata, allora la specifica dell’API fa parte dei requisiti e dovrebbe essere citata nel TRD. Se, d’altra parte, l’obiettivo è quello di sviluppare un’API nuova di zecca, allora la specifica API fa parte del progetto e dovrebbe essere descritta nel TDD. (Tuttavia, il documento dei requisiti ha ancora bisogno di specificare ciò che l’API sta cercando di realizzare.)

Scrivere il TDD

Al giorno d’oggi, è pratica comune scrivere i documenti tecnici in un sistema di documenti collaborativi, come Google Docs o Confluence; tuttavia questo non è un requisito assoluto. L’importante è che ci sia un modo per i membri del tuo team di essere in grado di fare commenti sul documento e segnalare errori e omissioni.

La maggior parte dei TDD sono tra una e dieci pagine. Anche se non c’è un limite massimo alla lunghezza di un TDD, documenti molto grandi saranno sia difficili da modificare che da assorbire per i lettori; considera la possibilità di dividerlo in documenti separati che rappresentano singoli passi o fasi dell’implementazione.

I diagrammi sono utili; ci sono un certo numero di strumenti online che puoi usare per incorporare illustrazioni nel documento, come draw.io o Lucidchart. Puoi anche usare strumenti offline come Inkscape per generare diagrammi SVG.

Il documento dovrebbe essere completo; idealmente, dovrebbe essere possibile per qualcuno diverso dall’autore del TDD implementare il progetto come scritto. Per esempio, se il progetto specifica l’implementazione di un’API, ogni endpoint API dovrebbe essere documentato. Se ci sono scelte di design sottili, dovrebbero essere segnalate.

Evitare gli errori comuni di scrittura

Probabilmente l’errore più comune che incontro nei TDD è una mancanza di contesto. Cioè, l’autore ha scritto, nel minor numero di parole possibile, come ha risolto il problema; ma non ha incluso alcuna informazione su quale fosse il problema, perché doveva essere risolto, o quali fossero le conseguenze della scelta di quella particolare soluzione.

Inoltre, è importante tenere a mente chi è il probabile lettore, e quale livello di comprensione ha. Se usate un termine che il lettore potrebbe non conoscere, non abbiate paura di aggiungere una definizione per esso.

Non c’è bisogno di dire che una buona grammatica e ortografia sono utili. Inoltre, evitate la tentazione dei giochi di parole o dell’ortografia “carina”; mentre i programmatori come classe tendono a giocare con il linguaggio, ho visto più di un caso in cui l’eccessiva frivolezza ha finito per costare al team sforzi sprecati a causa di malintesi. Va bene usare occasionalmente dell’umorismo o scegliere nomi colorati e memorabili per funzioni e sistemi, poiché questo aiuta le persone a ricordarli. Ma non lasciate che il vostro desiderio di mostrare quanto siete intelligenti diventi una distrazione.

Parlando di nomi, sceglieteli con attenzione; come Mark Twain scrisse una volta, “Scegliete la parola giusta, non la cugina di secondo grado”. C’è una tendenza degli ingegneri con un vocabolario povero ad usare gli stessi termini generici più e più volte per cose diverse, portando a sovraccarico e confusione. Per esempio, nominare una classe “DataManager” è vago e non vi dice nulla su ciò che effettivamente fa; allo stesso modo un pacchetto o una directory chiamata “utils” potrebbe contenere virtualmente qualsiasi cosa. Consultate un thesaurus se avete bisogno di trovare una parola migliore, o meglio, un database specializzato di sinonimi come WordNet.

TTDD Template

Quando si scrive un TDD, può essere utile iniziare con un template standard. Il seguente è un modello che ho usato in un certo numero di progetti. Notate che questo modello dovrebbe essere personalizzato dove necessario; siete liberi di cancellare le sezioni che non si applicano, aggiungere altre sezioni, o rinominare le intestazioni come appropriato.