Podcast na Softwarová dokumentace a její principy

Kapitoly

Paradox programátora

K čemu jsou komentáře?

Jeden projekt, jiná pravidla

Pohledy na architekturu

Méně je někdy více

Nástroje na pomoc

Proč se trápit s dokumentací?

Forma versus obsah

Chytré nástroje a standardy

Znovupoužití je král

Úvod do XML

Pravidla a syntaxe XML

Dokumentace v Javě

Závěr a rozloučení

Přepis

Tomáš: ...takže ten nejlepší programátor na světě napíše geniální kód, ale když k němu nenapíše ani řádku vysvětlení, je to vlastně skoro k ničemu?

Karolína: Přesně tak! Je to jako vynalézt ten nejlepší motor na světě a pak zahodit manuál. Nikdo ho neopraví, nikdo ho nevylepší a nikdo neví, jak ho použít!

Tomáš: To je skvělé přirovnání! Vítejte u Studyfi Podcast, kde se dnes ponoříme do světa softwarového inženýrství.

Karolína: Tak pojďme rovnou na věc. Spousta lidí si myslí, že psaní komentářů do kódu je ztráta času. „Vždyť já vím, co jsem napsal,“ říkají si.

Tomáš: Jo, to znám. „Můj kód je přece samo-vysvětlující.“ Jasně…

Karolína: Přesně. Jenže to platí jen do chvíle, než od toho projektu na týden odejdeš. Nebo stačí dovolená. Pak se vrátíš, koukáš na vlastní kód a ptáš se, co tímhle ten autor jako myslel?

Tomáš: A přitom ten autor jsi ty sám! To se mi stalo víckrát, než bych přiznal.

Karolína: Stává se to všem. A to je jen jeden důvod. Dnešní software je týmová práce. Komentáře jsou vzkazy pro tvé kolegy, aby mohli navázat na tvoji myšlenku. Bez nich je to skoro nemožné.

Tomáš: A co když chci svůj kód použít jako nějakou knihovnu pro ostatní? Tedy dát jim nástroj, ale neukazovat jim, jak přesně funguje uvnitř.

Karolína: Skvělý postřeh! V tom případě je kvalitní dokumentace naprosto klíčová. Bez ní by byla tvoje úžasná knihovna prakticky nepoužitelná.

Tomáš: Dobře, takže dokumentovat musíme. Znamená to, že ke každému projektu musím sepsat stovky stran textu? To zní jako noční můra.

Karolína: Vůbec ne! A to je na tom to krásné. Úroveň dokumentace se liší projekt od projektu. Není to žádné dogma. Je to o efektivitě.

Tomáš: Jak to myslíš?

Karolína: Představ si, že pracuješ v malém týmu, všichni sedíte v jedné místnosti a vyvíjíte jednoduchou appku. Doména je známá. V takovém případě vám jako dokumentace architektury může stačit fotka náčrtku z tabule.

Tomáš: Vážně? Jen fotka z mobilu?

Karolína: Přesně tak. Proč ne, pokud to všem dává smysl a šetří to čas? Ale teď si představ opak. Velký, distribuovaný tým, nová složitá technologie, neznámá oblast... Tam už budeš potřebovat mnohem víc.

Tomáš: Třeba slovník pojmů, detailní modely, jak spolu komponenty komunikují, a tak dál?

Karolína: Přesně. Cílem není vytvořit co nejvíc dokumentace, ale tu správnou dokumentaci pro daný projekt.

Tomáš: Dobře, řekněme, že máme složitější projekt. Co konkrétně bychom měli v dokumentaci architektury zachytit?

Karolína: Měli bychom zachytit několik základních pohledů na systém. Zaprvé, statický pohled – z jakých částí se aplikace skládá. To si můžeš představit jako půdorys budovy. Tady jsou třídy, tady jsou balíčky.

Tomáš: Rozumím. A dál?

Karolína: Zadruhé, dynamické chování. Tedy jak spolu ty jednotlivé části komunikují. To je jako sledovat, jak lidé v té budově chodí z místnosti do místnosti. K tomu se skvěle hodí třeba sekvenční diagramy z UML.

Tomáš: A co pohled uživatele? Toho přece nezajímá, jaké máme třídy.

Karolína: Přesně! To je třetí klíčový pohled. K tomu slouží takzvané „use case“, neboli případy užití. Ty popisují, co systém dělá z pohledu uživatele, jaké funkce mu nabízí. Je to funkční pohled.

Tomáš: Takže máme různé modely, různé pohledy... Nemůže se stát, že toho budeme mít až moc? Že se v té dokumentaci nakonec ztratíme?

Karolína: Může, a to je obrovské riziko! Čím víc dokumentace máš a na čím více místech opakuješ stejné informace, tím víc práce máš s její aktualizací.

Tomáš: A tím větší je šance, že někde bude chyba nebo nekonzistence. V jednom dokumentu bude verze A, ve druhém verze B.

Karolína: Přesně tak! Proto já osobně preferuji minimalistický, efektivní přístup. Existují i velmi vědecké metody, třeba od Software Engineering Institute, které se na dokumentaci dívají skoro jako na samostatnou vědní disciplínu.

Tomáš: Takže méně je někdy více, pokud nechceš skončit s dokumentací, která je delší a složitější než samotný kód?

Karolína: Přesně jsi to vystihl. Cílem je srozumitelnost a efektivita, ne stohy papíru.

Tomáš: Tohle všechno zní jako spousta práce. Existují nějaké nástroje, které by nám tu, přiznejme si, občas nepříjemnou práci usnadnily?

Karolína: Samozřejmě. Nemusíme všechno psát ručně. Existují skvělé nástroje, které umí dokumentaci generovat přímo ze zdrojového kódu. Třeba Java má nástroj jménem JavaDoc.

Tomáš: Takže když píšu komentáře správným způsobem přímo do kódu, program mi z toho pak sám vytvoří hezkou dokumentaci?

Karolína: Přesně tak! To je jeden z nejefektivnějších způsobů. Další technologií, která v tomhle hodně pomáhá, je XML. Ale o tom si povíme víc třeba příště.

Tomáš: Dobře, takže jsme probrali návrh a specifikaci... ale teď mě napadá jedna věc, kterou programátoři, co znám, naprosto milují. Dokumentace.

Karolína: Jo, trefa do černého! Zeptat se vývojáře, aby napsal dokumentaci, je asi jako poprosit kočku, aby si dala vanu. Prostě to nechtějí dělat.

Tomáš: To je skvělé přirovnání! Ale proč je to vlastně tak důležité, když to všichni tak nesnáší?

Karolína: Protože software nikdy nežije ve vakuu. Neděláme to jen pro sebe. Představ si to takhle... tým údržby potřebuje vědět, jak je systém postavený, aby ho mohl opravit. Testeři zase musí vědět, co přesně má systém dělat, aby mohli ověřit, že to dělá správně.

Tomáš: A samozřejmě zákazníci...

Karolína: Přesně! Zákazníci potřebují uživatelskou příručku, aby věděli, na co mají klikat. Každá role potřebuje jiný pohled, jiný typ informací. Dokumentace je ten most mezi nimi.

Tomáš: Dobře, to dává smysl. Takže musíme mít štosy papírů a desítky dokumentů pro každý projekt?

Karolína: Vůbec ne! A to je klíčové. V agilním světě platí, že forma není tak důležitá jako obsah. Nejde o to mít metrové sloupce papíru, ale o to, jestli tu informaci vůbec máme a jestli ji sdílíme.

Tomáš: Takže méně je někdy více?

Karolína: Přesně. U malého týmu, který sedí v jedné místnosti a všichni vědí, na čem pracují, stačí třeba jen pár diagramů na tabuli a dobře okomentovaný kód. Naopak u obrovského mezinárodního projektu s desítkami týmů... tam už potřebujeme formálnější a detailnější dokumentaci.

Tomáš: Takže záleží na kontextu. Není jedno univerzální řešení pro všechny.

Karolína: Bingo! To je přesně ono. Cílem je mít *dostatečnou* dokumentaci, ne *maximální*. Chceme efektivitu, ne byrokracii.

Tomáš: Fajn, tomu rozumím. Existují nějaké nástroje, které by nám tu neoblíbenou práci trochu usnadnily?

Karolína: Samozřejmě! Programátoři jsou chytří a líní, takže si vymysleli způsoby, jak to automatizovat. Skvělým příkladem je JavaDoc. To je nástroj pro jazyk Java.

Tomáš: Jak to funguje?

Karolína: Jednoduše. Píšeš komentáře přímo do kódu podle určitých pravidel. Pak spustíš nástroj JavaDoc a ten ti z těch komentářů automaticky vygeneruje hezkou, přehlednou technickou dokumentaci ve formátu HTML. Nemusíš nic psát dvakrát.

Tomáš: To zní skvěle! A co nějaké obecnější standardy? Něco jako... kuchařka pro dobrou dokumentaci?

Karolína: Existuje. Například standard IEEE 1063. Ten v podstatě říká, co by měla kvalitní uživatelská dokumentace minimálně obsahovat. Jakou má mít strukturu, formát, že musí být kompletní, přesná... Je to takové vodítko, aby se na nic důležitého nezapomnělo.

Tomáš: Takže nemusíme znovu vynalézat kolo.

Karolína: Přesně. Můžeme se opřít o osvědčené postupy.

Tomáš: Zmínila jsi, že s JavaDocem nemusíme psát věci dvakrát. To je asi hlavní myšlenka, ne?

Karolína: Rozhodně! Princip znovupoužití je tady naprosto zásadní. Nechceme vytvářet dokumenty, které pak jen leží ladem. Snažíme se využít to, co už máme.

Tomáš: Jako třeba co konkrétně?

Karolína: Vzpomínáš, jak jsme se bavili o use case scénářích, kde popisujeme, jak uživatel interaguje se systémem? Třeba výběr peněz z bankomatu.

Tomáš: Jasně, ty kroky, co se dějí.

Karolína: Tak přesně tyhle textové scénáře můžeš vzít, lehce je upravit, přidat pár obrázků a máš hotovou kapitolu do uživatelské příručky. Ušetřil jsi spoustu práce a zajistil jsi, že manuál odpovídá původním požadavkům.

Tomáš: Páni, to je chytré. Takže dokumentace vlastně nemusí být taková noční můra. Je to spíš o chytrém přístupu a využití toho, co už existuje.

Karolína: Přesně tak. Je to další dílek skládačky softwarového inženýrství. A když už jsme u skládání... dalším klíčovým dílkem je samotná implementace a testování, na které se podíváme příště.

Tomáš: Takže jsme probrali, jak HTML dává strukturu webu pro lidi. Ale co když potřebujeme, aby i počítače rozuměly významu těch dat?

Karolína: Přesně tak, Tomáši! A právě tady na scénu přichází XML, neboli Extensible Markup Language.

Tomáš: Rozšiřitelný značkovací jazyk... To zní důležitě.

Karolína: To taky je! Představ si to takhle... v XML si můžeš vytvářet vlastní, úplně specifické značky, takzvané tagy. Takže místo obecného tagu máš třeba <autor>, <nazev> nebo <verze>. Okamžitě víš, o co jde.

Tomáš: Aha! Takže ta data si sama nesou svůj popis. To musí být naprosto skvělé pro vyhledávání a strojové zpracování.

Karolína: Přesně! Ale s tou volností přichází i velká zodpovědnost. XML má totiž mnohem přísnější pravidla než HTML.

Tomáš: Jaká pravidla například? Žádné zapomenuté uzavírací tagy?

Karolína: To v žádném případě! Všechny tagy musí být párové. Navíc XML rozlišuje velká a malá písmena, takže <Tag> a <tag> jsou dvě úplně jiné věci.

Tomáš: Rozumím, je to case-sensitive. Co dál?

Karolína: Každý dokument musí mít právě jeden kořenový element, který obaluje všechno ostatní. A hodnoty atributů musí být vždy v uvozovkách. Žádné výjimky.

Tomáš: Působí to skoro... matematicky přesně. Ale jak ten systém ví, jaká struktura je správná?

Karolína: Skvělá otázka! K tomu se používá DTD nebo takzvané XML Schéma, které definují povolenou strukturu. Ale k tomu se dostaneme hned vzápětí.

Tomáš: Dobře, probrali jsme toho opravdu hodně. Ale máme před sebou poslední velké téma... Javu. A hlavně, jak se neztratit ve vlastním kódu.

Karolína: Přesně tak! A to nás přivádí k něčemu, co se jmenuje Javadoc. Je to neuvěřitelně užitečný nástroj od Sun Microsystems.

Tomáš: Javadoc... zní to skoro jako nějaký zákon. Co to přesně dělá?

Karolína: Představ si to takhle. Je to nástroj, který automaticky generuje webovou stránku s dokumentací přímo z komentářů ve tvém zdrojovém kódu. Pro dokumentaci API je to naprostá záchrana.

Tomáš: Takže napíšu komentář a ten se stane součástí profesionálně vypadající webové stránky? To je skvělé.

Karolína: V podstatě ano! Ale má to háček. Ten nástroj je sice chytrý, ale neumí číst myšlenky. Když svou třídu pojmenuješ třeba 'Pr' a nenapíšeš srozumitelné komentáře, výsledná dokumentace bude k ničemu.

Tomáš: Jasně. Odpad dovnitř, odpad ven. Takže to automatizuje formátování, ale kvalita obsahu je pořád na tobě.

Karolína: Přesně tak. Pomůže ti to postavit dům, ale cihly musíš dodat sám. Dobré komentáře a smysluplné názvy jsou základ.

Tomáš: To je perfektní tečka na závěr. Dobré návyky jsou klíčové. Karolíno, to je pro dnešek vše. Prošli jsme všechno od XML schémat až po Javu. Díky moc, že jsi nám to všechno objasnila.

Karolína: Bylo mi potěšením! Díky za pozvání.

Tomáš: A díky všem za poslech Studyfi Podcastu. Uslyšíme se příště!