Engineering Insights
O abilitate importantă pentru orice inginer software este scrierea documentelor de proiectare tehnică (TDD), denumite și documente de proiectare tehnică (EDD). Aici, în acest articol, vă ofer câteva sfaturi pentru a scrie documente de proiectare bune și ce greșeli să evitați.
O singură avertizare: Echipe diferite vor avea standarde și convenții diferite pentru proiectarea tehnică. Nu există un standard la nivel de industrie pentru procesul de proiectare și nici nu ar putea exista, deoarece diferite echipe de dezvoltare vor avea nevoi diferite în funcție de situația lor. Ceea ce voi descrie este un răspuns posibil, bazat pe propria mea experiență.
Să începem cu elementele de bază: Ce este un document de proiectare tehnică și cum se integrează în procesul de proiectare?
Un document de proiectare tehnică descrie o soluție la o anumită problemă tehnică. Este o specificație sau o „schiță de proiectare” pentru un program sau o caracteristică software.
Funcția principală a unui TDD este de a comunica membrilor echipei detaliile tehnice ale activității care urmează să fie efectuate. Cu toate acestea, există un al doilea scop care este la fel de important: procesul de scriere a TDD vă forțează să vă organizați gândurile și să luați în considerare fiecare aspect al proiectării, asigurându-vă că nu ați omis nimic.
Documentele de proiectare tehnică fac adesea parte dintr-un proces mai amplu care are, de obicei, următoarele etape:
- Se definesc cerințele produsului. Acestea vor fi de obicei reprezentate de un document privind cerințele produsului (PRD). PRD-ul specifică ceea ce trebuie să facă sistemul, din perspectiva unui utilizator sau a unui agent extern.
- Se definesc cerințele tehnice. Cerințele produsului sunt transpuse în cerințe tehnice – ceea ce trebuie să realizeze sistemul, dar acum cum o face. Rezultatul acestei etape este un document privind cerințele tehnice (Technical Requirements Document – TRD).
- Proiectare tehnică. Aceasta conține o descriere tehnică a soluției la cerințele descrise în etapele anterioare. TDD este rezultatul acestei etape.
- Implementare. Aceasta este etapa în care soluția este efectiv construită.
- Testare. Sistemul este testat în raport cu PRD și TRD pentru a se asigura că acesta îndeplinește efectiv cerințele specificate.
Între fiecare dintre aceste etape există, de obicei, un proces de revizuire pentru a se asigura că nu s-au făcut greșeli. În cazul în care sunt detectate erori, neînțelegeri sau ambiguități, acestea trebuie corectate înainte de a trece la etapa următoare.
Acest proces este foarte variabil; setul de etape enumerate aici se va schimba de la caz la caz. De exemplu:
- Pentru caracteristicile mai mici care nu implică o mare complexitate, etapele 2 și 3 vor fi adesea combinate într-un singur document.
- Dacă caracteristica implică un număr mare de necunoscute sau un anumit nivel de cercetare, poate fi necesar să se construiască o implementare de probă de concept înainte de a finaliza proiectul tehnic.
Acest proces are loc, de asemenea, la diferite scări și niveluri de granularitate. Un PRD / TRD / TDD se poate referi la proiectarea unui întreg sistem sau doar a unei singure caracteristici. În majoritatea mediilor, procesul este, de asemenea, ciclic – fiecare ciclu de proiectare/implementare se bazează pe munca celui precedent.
Linia de demarcație dintre TRD și TDD poate fi puțin neclară uneori. De exemplu, să presupunem că dezvoltați un server care comunică prin intermediul unui API RESTful. Dacă obiectivul este să vă conformați unei API deja stabilite și documentate, atunci specificația API face parte din cerințe și ar trebui să fie menționată în TRD. Dacă, pe de altă parte, obiectivul este de a dezvolta o API complet nouă, atunci specificația API face parte din proiectare și ar trebui să fie descrisă în TDD. (Cu toate acestea, documentul privind cerințele trebuie să precizeze în continuare ce încearcă să realizeze API-ul.)
Scrierea TDD
În zilele noastre, este o practică obișnuită să se scrie documentele tehnice într-un sistem colaborativ de documente, cum ar fi Google Docs sau Confluence; cu toate acestea, aceasta nu este o cerință absolută. Important este să existe o modalitate prin care membrii echipei dumneavoastră să poată face comentarii asupra documentului și să semnaleze erorile și omisiunile.
Majoritatea TDD-urilor au între una și zece pagini. Deși nu există o limită superioară a lungimii unui TDD, documentele foarte mari vor fi atât dificil de editat, cât și greu de asimilat de către cititori; luați în considerare posibilitatea de a-l împărți în documente separate care să reprezinte etape sau faze individuale ale implementării.
Diagramele sunt utile; există o serie de instrumente online pe care le puteți utiliza pentru a încorpora ilustrații în document, cum ar fi draw.io sau Lucidchart. De asemenea, puteți utiliza instrumente offline, cum ar fi Inkscape, pentru a genera diagrame SVG.
Documentul ar trebui să fie complet; în mod ideal, ar trebui să fie posibil ca altcineva decât autorul TDD să implementeze proiectul așa cum este scris. De exemplu, dacă proiectarea specifică o implementare a unei API, fiecare punct final API ar trebui să fie documentat. Dacă există alegeri subtile de proiectare, acestea ar trebui să fie evidențiate.
Evitați greșelile comune de scriere
Probabil cea mai frecventă greșeală pe care o întâlnesc în TDD-uri este lipsa de context. Adică, autorul a scris, în cât mai puține cuvinte pe care le-a putut gestiona, cum a rezolvat problema; dar nu a inclus nicio informație despre care era problema, de ce trebuia rezolvată sau care au fost consecințele alegerii acelei anumite soluții.
De asemenea, este important să aveți în vedere cine este cititorul probabil și ce nivel de înțelegere are acesta. Dacă folosiți un termen pe care cititorul ar putea să nu-l cunoască, nu vă fie teamă să adăugați o definiție pentru acesta.
Nu este nevoie să mai spunem că o bună gramatică și ortografie sunt de ajutor. De asemenea, evitați tentația jocurilor de cuvinte sau a ortografiei „drăguțe”; deși programatorilor, ca și clasă, tinde să le placă să se joace cu limbajul, am văzut mai mult de un caz în care frivolitatea excesivă a sfârșit prin a costa echipa eforturi irosite din cauza neînțelegerilor. Este în regulă să folosiți ocazional umorul sau să alegeți nume colorate și memorabile pentru caracteristici și sisteme, deoarece acest lucru îi ajută pe oameni să și le amintească. Dar nu lăsați ca dorința de a arăta cât de inteligent sunteți să devină o distragere a atenției.
Pe când vorbim de nume, alegeți-le cu grijă; așa cum a scris odată Mark Twain, „Alegeți cuvântul potrivit, nu pe vărul său de-al doilea”. Există o tendință a inginerilor cu un vocabular sărac de a folosi aceiași termeni generici la nesfârșit pentru lucruri diferite, ceea ce duce la supraîncărcare și confuzie. De exemplu, numirea unei clase „DataManager” este vagă și nu vă spune nimic despre ceea ce face de fapt; în același mod, un pachet sau un director numit „utils” ar putea conține practic orice. Consultați un tezaur dacă aveți nevoie să găsiți un cuvânt mai bun sau, mai bine, o bază de date specializată de sinonime, cum ar fi WordNet.
Șablon TDD
Când scrieți un TDD, poate fi util să începeți cu un șablon standard. Următorul este un șablon pe care l-am folosit în mai multe proiecte. Rețineți că acest șablon trebuie personalizat acolo unde este necesar; sunteți liber să ștergeți secțiunile care nu se aplică, să adăugați secțiuni suplimentare sau să redenumiți rubricile, după caz.
.