Engineering Insights

Talin

Sledovat

3. ledna, 2019 – 7 minut čtení

Důležitou dovedností každého softwarového inženýra je psaní dokumentace technického návrhu (TDD), označované také jako dokumentace technického návrhu (EDD). V tomto článku nabízím několik rad, jak psát dobré návrhové dokumenty a jakých chyb se vyvarovat.

Jedno upozornění: Různé týmy budou mít různé standardy a konvence pro technický návrh. Pro proces návrhu neexistuje a ani nemůže existovat žádný oborový standard, protože různé vývojové týmy budou mít v závislosti na situaci různé potřeby. To, co popíšu, je jedna z možných odpovědí, která vychází z mých vlastních zkušeností.

Začněme od základů: Co je to dokumentace technického návrhu a jak zapadá do procesu návrhu?

Dokumentace technického návrhu popisuje řešení daného technického problému. Je to specifikace neboli „návrhový plán“ softwarového programu nebo funkce.

Primární funkcí TDD je sdělit členům týmu technické detaily práce, která se má provést. Existuje však i druhý účel, který je stejně důležitý: proces psaní TDD vás nutí uspořádat si myšlenky a zvážit všechny aspekty návrhu a ujistit se, že jste nic nevynechali.

Technické dokumenty návrhu jsou často součástí většího procesu, který má obvykle následující kroky:

1. Definují se požadavky na produkt. Ty budou obvykle reprezentovány dokumentem požadavků na výrobek (PRD). PRD specifikuje, co musí systém dělat z pohledu uživatele nebo externího agenta.
2. Definují se technické požadavky. Požadavky na produkt jsou převedeny na technické požadavky – co musí systém splnit, ale nyní i jak to udělá. Výstupem tohoto kroku je dokument technických požadavků (TRD).
3. Technický návrh. Ten obsahuje technický popis řešení požadavků nastíněných v předchozích krocích. Výstupem tohoto kroku je TDD.
4. Implementace. V této fázi se řešení skutečně vytváří.
5. Testování. Systém se testuje podle PRD a TRD, aby se zajistilo, že skutečně splňuje zadané požadavky.

Mezi každou z těchto fází obvykle probíhá proces přezkoumání, aby se zajistilo, že nedošlo k chybám. Pokud jsou zjištěny nějaké chyby, nedorozumění nebo nejasnosti, je třeba je před přechodem k dalšímu kroku opravit.

Tento proces je velmi variabilní; soubor zde uvedených kroků se bude měnit případ od případu. Například:

• U menších funkcí, které nezahrnují mnoho složitostí, budou kroky 2 a 3 často spojeny do jediného dokumentu.
• Pokud funkce zahrnuje velké množství neznámých nebo určitou úroveň výzkumu, může být nutné před dokončením technického návrhu zkonstruovat zkušební implementaci.

Tento proces také probíhá v různých měřítkách a úrovních granularity. PRD / TRD / TDD se může týkat návrhu celého systému nebo jen jedné funkce. Ve většině prostředí je tento proces také cyklický – každý cyklus návrhu/implementace navazuje na práci toho předchozího.

Dělící čára mezi TRD a TDD může být někdy trochu nejasná. Předpokládejme například, že vyvíjíte server, který komunikuje prostřednictvím rozhraní RESTful API. Pokud je cílem vyhovět již zavedenému a zdokumentovanému API, pak je specifikace API součástí požadavků a měla by být uvedena v TRD. Pokud je naopak cílem vyvinout zcela nové API, pak je specifikace API součástí návrhu a měla by být popsána v TDD. (Dokument s požadavky však stále musí specifikovat, čeho se API snaží dosáhnout.)

Psaní TDD

V dnešní době je běžnou praxí psát technické dokumenty v systému pro spolupráci, jako jsou Dokumenty Google nebo Confluence; není to však absolutní požadavek. Důležité je, aby existoval způsob, jak mohou členové vašeho týmu dokument připomínkovat a upozorňovat na chyby a opomenutí.

Většina TDD má od jedné do deseti stran. Ačkoli horní hranice délky TDD neexistuje, velmi rozsáhlé dokumenty se budou jednak obtížně upravovat, jednak je čtenáři těžko vstřebají; zvažte jejich rozdělení na samostatné dokumenty představující jednotlivé kroky nebo fáze implementace.

Pomocné jsou diagramy; existuje řada online nástrojů, které můžete použít k vložení ilustrací do dokumentu, například draw.io nebo Lucidchart. K vygenerování diagramů SVG můžete použít i offline nástroje, například Inkscape.

Dokument by měl být důkladný; v ideálním případě by mělo být možné, aby návrh v napsané podobě implementoval i někdo jiný než autor TDD. Pokud například návrh specifikuje implementaci rozhraní API, měl by být zdokumentován každý koncový bod API. Pokud existují jemné volby návrhu, mělo by se na ně upozornit.

Vyhněte se běžným chybám při psaní

Pravděpodobně nejčastější chybou, se kterou se v TDD setkávám, je nedostatek kontextu. To znamená, že autor napsal co nejmenším počtem slov, jak problém vyřešil; ale neuvedl žádné informace o tom, co je to za problém, proč je třeba ho řešit nebo jaké jsou důsledky volby tohoto konkrétního řešení.

Také je důležité mít na paměti, kdo je pravděpodobný čtenář a jakou má úroveň porozumění. Pokud použijete termín, který by čtenář nemusel znát, nebojte se přidat jeho definici.

Není snad třeba zdůrazňovat, že dobrá gramatika a pravopis jsou užitečné. Vyvarujte se také pokušení hrát si se slovíčky nebo „roztomilým“ pravopisem; programátoři jako třída si sice rádi hrají s jazykem, ale už jsem viděl nejeden případ, kdy přílišná lehkovážnost nakonec stála tým zbytečné úsilí kvůli nedorozumění. Je v pořádku občas použít humor nebo zvolit barvité, zapamatovatelné názvy funkcí a systémů, protože to pomáhá lidem si je zapamatovat. Nedovolte však, aby se vaše touha předvést, jak jste chytří, stala rušivým elementem.

Když už mluvíme o názvech, vybírejte je pečlivě; jak kdysi napsal Mark Twain: „Vyberte správné slovo, ne jeho bratrance z druhého kolena“. Inženýři s chudým slovníkem mají tendenci používat stále stejné obecné výrazy pro různé věci, což vede k přetížení a zmatení. Například pojmenování třídy „DataManager“ je vágní a neříká nic o tom, co vlastně dělá; ze stejného důvodu může balík nebo adresář pojmenovaný „utils“ obsahovat prakticky cokoli. Pokud potřebujete najít lepší slovo, nahlédněte do tezauru, nebo ještě lépe do specializované databáze synonym, jako je WordNet.

Šablona TDD

Při psaní TDD může být užitečné začít se standardní šablonou. Následuje šablona, kterou jsem použil v řadě projektů. Všimněte si, že tuto šablonu je třeba v případě potřeby upravit; můžete libovolně odstranit oddíly, které se vás netýkají, přidat další oddíly nebo podle potřeby přejmenovat nadpisy.