Engineering Insights
Minden szoftvermérnök számára fontos készség a műszaki tervdokumentáció (TDD), más néven mérnöki tervdokumentáció (EDD) írása. Ebben a cikkben néhány tanácsot adok a jó tervezési dokumentáció megírásához, és hogy milyen hibákat érdemes elkerülni.
Egy figyelmeztetés: A különböző csapatoknak különböző szabványai és konvenciói vannak a műszaki tervezésre vonatkozóan. A tervezési folyamatra nincs iparági szintű szabvány, és nem is lehetne, mivel a különböző fejlesztőcsapatoknak a helyzetüktől függően eltérő igényeik vannak. Amit leírok, az egy lehetséges válasz, saját tapasztalataim alapján.
Kezdjük az alapokkal: Mi az a műszaki tervdokumentáció, és hogyan illeszkedik a tervezési folyamatba?
A műszaki tervdokumentáció egy adott műszaki probléma megoldását írja le. Ez egy specifikáció, vagy “tervezési tervrajz” egy szoftverprogramhoz vagy funkcióhoz.
A TDD elsődleges funkciója, hogy az elvégzendő munka technikai részleteit közölje a csapat tagjaival. Van azonban egy másik, ugyanilyen fontos cél is: a TDD megírásának folyamata arra kényszeríti Önt, hogy rendszerezze gondolatait, és a tervezés minden aspektusát figyelembe vegye, biztosítva, hogy semmit sem hagyott ki.
A műszaki tervdokumentáció gyakran egy nagyobb folyamat része, amely jellemzően a következő lépésekből áll:
- A termékkövetelmények meghatározása. Ezeket jellemzően egy termékkövetelmény-dokumentum (PRD) képviseli. A PRD meghatározza, hogy a rendszernek mit kell tennie egy felhasználó vagy külső szereplő szemszögéből.
- A műszaki követelmények meghatározása. A termékkövetelményeket műszaki követelményekre fordítják le – mit kell a rendszernek teljesítenie, de most már azt is, hogyan teszi ezt. Ennek a lépésnek a kimenete egy műszaki követelménydokumentum (TRD).
- Műszaki tervezés. Ez tartalmazza az előző lépésekben felvázolt követelmények megoldásának műszaki leírását. A TDD ennek a lépésnek a kimenete.
- Megvalósítás. Ez az a szakasz, amikor a megoldás ténylegesen megépül.
- Tesztelés. A rendszert a PRD és a TRD alapján tesztelik, hogy a rendszer valóban teljesíti-e a meghatározott követelményeket.
Az egyes szakaszok között jellemzően egy felülvizsgálati folyamat zajlik, amely biztosítja, hogy nem követtek el hibákat. Ha bármilyen hibát, félreértést vagy kétértelműséget észlelnek, ezeket ki kell javítani, mielőtt a következő lépésre lépnének.
Ez a folyamat nagyon változó; az itt felsorolt lépések sora esetről esetre változik. Például:
- Kisebb, nem túl bonyolult funkciók esetében a 2. és 3. lépés gyakran egyetlen dokumentumban egyesül.
- Ha a funkció nagyszámú ismeretlent vagy bizonyos szintű kutatást foglal magában, előfordulhat, hogy a műszaki terv véglegesítése előtt egy proof-of-concept megvalósítást kell készíteni.
Ez a folyamat is különböző léptékben és szemcseméretű szinteken történik. Egy PRD / TRD / TDD vonatkozhat egy teljes rendszer tervezésére, vagy csak egyetlen funkcióra. A legtöbb környezetben a folyamat szintén ciklikus – minden egyes tervezési/megvalósítási ciklus az előző ciklus munkájára épül.
A TRD és TDD közötti határvonal néha kissé elmosódott lehet. Tegyük fel például, hogy egy RESTful API-n keresztül kommunikáló kiszolgálót fejlesztünk. Ha a cél egy már létrehozott és dokumentált API-nak való megfelelés, akkor az API specifikáció a követelmények része, és a TRD-ben hivatkozni kell rá. Ha viszont a cél egy teljesen új API kifejlesztése, akkor az API-specifikáció a tervezés része, és azt a TDD-ben kell leírni. (A követelménydokumentumnak azonban továbbra is meg kell határoznia, hogy mit akar elérni az API.)
A TDD megírása
Elterjedt gyakorlat manapság, hogy a műszaki dokumentumokat egy kollaboratív dokumentumrendszerben, például a Google Docs-ban vagy a Confluence-ben írják; ez azonban nem feltétlenül követelmény. A lényeg, hogy legyen mód arra, hogy a csapattagok megjegyzéseket fűzhessenek a dokumentumhoz, és rámutathassanak a hibákra és hiányosságokra.
A legtöbb TDD egy és tíz oldal között van. Bár a TDD terjedelmének nincs felső határa, a nagyon nagy dokumentumokat nehéz lesz szerkeszteni, és az olvasók számára is nehezen befogadhatóak lesznek; fontolja meg, hogy a megvalósítás egyes lépéseit vagy fázisait bemutató külön dokumentumokra bontja fel.
A diagramok hasznosak; számos olyan online eszköz létezik, amellyel illusztrációkat ágyazhat a dokumentumba, például a draw.io vagy a Lucidchart. Az SVG-diagramok létrehozásához olyan offline eszközöket is használhat, mint például az Inkscape.
A dokumentumnak alaposnak kell lennie; ideális esetben a TDD szerzőjén kívül más is megvalósíthatja a tervezetet a leírtak szerint. Ha például a terv egy API megvalósítását írja elő, minden egyes API végpontot dokumentálni kell. Ha vannak finom tervezési döntések, azokat meg kell nevezni.
A gyakori írói hibák elkerülése
Vélhetően a leggyakoribb hiba, amivel TDD-kben találkozom, a kontextus hiánya. Ez azt jelenti, hogy a szerző a lehető legkevesebb szóval leírta, hogyan oldotta meg a problémát; de nem tartalmazott semmilyen információt arról, hogy mi volt a probléma, miért kellett megoldani, vagy milyen következményei voltak annak, hogy ezt a bizonyos megoldást választotta.
Azt is fontos szem előtt tartani, hogy ki a valószínű olvasó, és milyen szintű megértéssel rendelkezik. Ha olyan kifejezést használsz, amelyet az olvasó esetleg nem ismer, ne félj hozzáadni egy definíciót.
Azt aligha kell mondani, hogy a jó nyelvtan és helyesírás hasznos. Kerülje továbbá a szójátékok vagy az “aranyos” helyesírás kísértését; bár a programozók általában szeretnek játszani a nyelvvel, nem egy olyan esetet láttam már, amikor a túlzott könnyelműség a félreértések miatt a csapat elvesztegetett erőfeszítéseibe került. Nem baj, ha időnként humort használunk, vagy színes, megjegyezhető neveket választunk a funkcióknak és rendszereknek, mivel ez segít az embereknek emlékezni rájuk. De ne hagyja, hogy az a vágya, hogy megmutassa, mennyire okos, elvonja a figyelmét.
Apropó, nevek: gondosan válassza meg őket; ahogy Mark Twain írta egyszer: “Válassza a megfelelő szót, ne annak másod-unokatestvérét”. A szegényes szókinccsel rendelkező mérnökök hajlamosak újra és újra ugyanazokat az általános kifejezéseket használni különböző dolgokra, ami túlterheléshez és zűrzavarhoz vezet. Például egy osztály “DataManager” elnevezése homályos, és semmit sem árul el arról, hogy valójában mit csinál; ugyanígy egy “utils” nevű csomag vagy könyvtár gyakorlatilag bármit tartalmazhat. Konzultáljon egy szinonimaszótárral, ha jobb szót kell találnia, vagy még jobb, ha egy speciális szinonima-adatbázist, például a WordNet-et használja.
TDD sablon
A TDD megírásakor hasznos lehet egy szabványos sablonnal kezdeni. A következő egy sablon, amelyet számos projektben használtam. Vegye figyelembe, hogy ezt a sablont szükség esetén testre kell szabni; nyugodtan törölheti az oda nem illő szakaszokat, hozzáadhat további szakaszokat, vagy adott esetben átnevezheti a címsorokat.