“Stará programátorská moudrost praví, že zdrojový kód je tou nejlepší dokumentací.”
Už ani nevím, kde jsem podobnou blbost slyšel poprvé, ale co je zarážející, že si to mnoho lidí myslí a řídí se podle toho. Ano, na některých otevřených platformách opravdu jedinou dokumentaci najdete ve složce src, totiž ve zdrojovém kódu, dost často tam bývá i nastavení a konfigurace aplikací, ale to je trochu jiná pohádka. Tento článek, jestli se tomu tak dá říct, je takový můj výbuch dlouhodobého zoufalství. Už šílím z aplikací a projektů, kde jejich autor zapomněl na podle mě jednu z nejdůležitějších věcí. Často ani nezapomněl, ale prostě se na ni vysral.
Můžete psát sebelepší kód s dobrými a kvalitními komentáři, můžete se sebevíc snažit, ale jakmile je vaše aplikace trochu větší, vyplatí se udělat k ní dokumentaci. Tedy myslím tím dokumentaci vývojářskou, kterou si po čase přečtete, až budete v kódu dělat nějaké změny.
Proč? Vždyť je to otrava. Znám stovky lidí, kteří nesnáší psaní dokumentace, a když už opravdu nějakou píší (většinou je k tomu někdo donutí), funguje to asi takhle: první den se pustí Word a pak si onen člověk pustí seriál, asi o pěti dílech se už prohlašuje, že jsou fakticky poslední a že už se pak bude psát ta dokumentace. Další den se napíše nadpis a ti otrlejší dají i nějaký úvod. Po týdnu, když už tlačí deadline, se konečně spíchne něco, co je nejkratší přípustné (ale zase ne moc krátké, aby to prošlo u tyrana, který to zadal). Kvalita těchto dokumentů bývá dosti nevalná, ale většinou to projde, kontroluje se to stupnicí typu Boolean - je anebo není. Mimochodem některé liščí formy života mají podobný problém s Powerpointem a s děláním prezentací, v jistých případech to došlo až k totálnímu nenávidění a alergii na tuto v zásadě nevinnou aplikaci.
Znám ale šílence, kteří mají problém opačný, k dokumentaci se staví zodpovědně a dokonce je to, ano, čtete správn, baví psát. S tím se ale člověk nenarodí, většinou si to vypěstuje časem, kdy po pár nepořádnících přebere projekt, kde dokumentace má půl stránky (písmem velikosti 16) a je z první verze aplikace z roku jedna dva tři. Mezitím se z původně jednoduchého klikátka pro sekretářku stal velký účetní systém s databází o dvou stech tabulkách, je v něm bordel nejvyššího kalibru a některé části kódu jsou zapovězené, protože pokud tam něco změníte, už to nikdy nikdo nedá dohromady, protože nikdo neví, jak to funguje a co to vlastně má dělat. Osoba, která za to může, která to všechno začala, pochopitelně odešla zakládat další takovéhle nezdokumentované obludy a za větší prachy (tomu se říká život, ale dá se na to zvyknout).
Pokud máte alespoň trochu sociálního cítění a soucitu s tím, kdo přijde po vás a bude s tou aplikací muset něco dělat, napíšete k ní dokumentaci. To bývá relativně málo častý důvod, já to dělám (a myslím, že i mnoho dalších lidí) z trochu jiného motivu.
I když píšu nějakou kravinku na 10 minut, snažím se programovat pořádně. Málokdy opravdu naplácám jen tak pár řádek kódu, to už musí být extra jednoúčelová aplikace, která si ani nezaslouží uložit. Ať píšu prostě cokoliv, píšu kód tak, abych se za něj nemusel stydět a aby si o mě nikdo, kdo to někdy uvidí, neřekl “ježiš ten Herceg, to je ale čuně”. Pokud píšu větší projekt, už od začátku to má mít nějakou robustnost a připravenost na budoucí rozšiřování. Spoustu věcí je dobré dělat tak a tak, tohohle je dobré se vyvarovat, protože to či ono atd.
Dokumentace se hodí ze dvou důvodů. Pokud chvíli budete dělat na něčem jiném a vrátíte se po 14 dnech, zapomenete. Ano, v komentářích a konkrétních částech kódu se rozkoukáte relativně rychle, ale člověk velmi rychle zapomíná souvislosti, které nejsou vidět. Třeba to, že tahle třída dělá tohle, v tuhle chvíli a za této situace si zinicializuje támhletu jinou třídu, která pak zase dělá něco jiného a potřebuje k tomu něco odněkud jinud. A tohle z kódu nevykoukáte hned, protože se to nevejde na obrazovku. Můžete mít komentáře, ale způsoby, jak mezi sebou jednotlivé části komunikují, se v tomhle hledají špatně. A ty by se měly psát do dokumentace. Pak si tu stránku nebo dvě stačí přečíst a máte hned jasno.
Dalším důvodem je předání projektu někomu jinému. Já osobně si svého kódu vážím a strašně nerad vidím, že někdo, i když třeba dělá na stejném projektu, do mého kódu zasáhne a nadělá tam nepořádek. Ano, chápu, každý má svůj styl úprav v kódu, ale i když aby to nějak vypadalo, měl by se člověk snažit co nejvíce zapadnout. Když dělá na projektu víc lidí, ať má třeba každá část trochu jiné konvence (dohadovat se na každé blbosti nemá smysl, jestli budeme psát za dvěmi lomítky mezeru nebo ne je úplně jedno), ale když mi někdo sáhne do mojí metody a neudělá za // mezeru, přestože o tři řádky výš v mém komentáři je, mám sto chutí začít střílet.
Dokumentace by měla sloužit i pro lidi, kteří na projektu spolupracují. Pokud je kvalitní, mohou získat povědomí o postupech, jak původní autor dělal tohle (a teď nemyslím syntaxi, ta je vidět v kódu, ale i jiné věci), zachovat konvenci a dělat to stejně. Dovede mě hodně naštvat, když do projektu v ASP.NET napíšu komponentu CustomerPicker, popíšu ji v dokumentaci, a člověk, který si ji přečte, stejně na příští stránce udělá SqlDataSource a DropDownList a celé si to píše sám. To je prostě k vzteku, stejné věci se mají dělat všude stejně a k tomu je dokumentace, měla by obsahovat zažité postupy provádění věcí.
Pár rad, jak programovat slušně
Upozorňuji, že to jsou jen moje postřehy, ne nějaké obecné dogma. Ale myslím, že s většinou zkušených lidí se na tom shodneme. Jsou to taková moje pravidla, kterými se řídím.
1. Do dokumentace nepatří to, co je v komentářích, je zbytečné popisovat každý řádek v každé metodě.
2. Pokud nějaká metoda nebo třída implementuje nějaký složitější algoritmus, je dobré ho v dokumentaci popsat.
3. Dokumentace by rozhodně měla obsahovat popisy tříd a hlavně vysvětlení, jak spolu třídy spolupracují, jak na sobě závisí. Je vhodné popsat použité návrhové vzory nebo alespoň jejich náznaky. Důležité jsou obecné vztahy jednotlivých částí, konkrétní detaily už tolik ne. Je důležité, aby čtením člověk pochytil souvislosti a získal globální přehled o projektu, který z komentářů v kódu získat nelze.
4. Používat XML komentáře (dá se z nich vygenerovat část dokumentace s přehledem tříd a metody; záměrně říkám část, rozhodně by to neměla být jediná dokumentace, která k projektu je, ta je skoro k ničemu). Navíc se to při používání oněch metod a tříd ukazuje v IntelliSense, je pak snadné používat třídy někoho jiného.
5. Komentovat i důležitější akce uvnitř metod. Je zbytečné psát komentáře typu “do proměnné si vytáhnout součet a a b” nebo “pokud a je null, vrať b”, to každý vidí z toho řádku pod tím, je dobré ale napsat “do proměnné si vytáhnout produkty, které vyhovují daným kritériům”, protože to už z řádku není tak patrné a rozepsat ta kritéria slovně usnadní jejich pochopení, zvlášť když kritérium v kódu je Stav = 3. V komentáři samozřejmě nesmí být “vytáhnout zakázky se stavem 3”, ale “vytáhnout realizované zakázky za rok 2008”.
6. Pokud se v projektu používají nějaké ustálené konstrukce, je velmi vhodné je do dokumentace napsat. Člověk, který si ji přečte (a bude při tom vnímat), nenadělá v projektu chaos, bude vědět, co ten kód dělá a proč se to píše takhle. Nebude se snažit vymyslet to sám a neudělá tam chyby, které jste tam měli už taky, když jste tuhle konstrukci vymýšleli, a které jste už jednou hledali a opravili.
7. Dávejte do dokumentace kusy kódu a příklady použití nějaké třídy, hrozně to usnadní práci a je na tom vidět, jak se co správně používá, v jakém pořadí se volají metody atd.
8. Pokud přebíráte projekt, snažte se co nejvíc zachovat styl, jakým byl psán, ať to nevypadá “každý pes, jiná ves”. Pokud je to extra bastl, tak to pochopitelně nejde, aniž byste v sobě zapřeli veškerou svoji hrdost, máte-li jakou. Šílenci (jako třeba já) celý projekt metodu po metodě projdou (odkrokují) a aspoň ty největší prohřešky proti programátorské etiketě opraví, přičemž ten kód navíc doplní o komentáře atd. Je to mnoho práce navíc, ale je to skoro jediná možnost, jak pořádně pochopit, jak nějaká složitější a nezdokumentovaná aplikace vlastně funguje. Pokud je ten projekt velký a není na to čas, pak je to bohužel smůla. Nemá ale ani cenu se s tím snažit moc nic dělat a zachraňovat to. Já jsem všechny pochybné projekty raději celé prošel a zkultivoval (dost drasticky, původní autoři ten kód nemohli ani poznat). Ale uznávám, že to není ono.
9. Při programování přemýšlejte a po dopsání nějakého většího celku napište dokumentaci. Vyplatí se to. Během psaní často narazíte na věci, které by se ještě daly trochu změnit nebo upravit, anebo se sami ujistíte, že jste to napsali a navrhli správně atd. To se mi stává poměrně často, zvlášť když napíšu tunu kódu, která není jak testovat, a potom, co dopíšu poslední metodu si už nedovybavuji všechny souvislosti. Psaním dokumentace provádíte vlastně i druhou kontrolu chyb - ne nějakých logických chyb, ale i chyb koncepčních, chyb typu tahle metoda by se měla jmenovat takhle, tahle metoda by chtěla rozdělit, tyhle by se měly přesunout sem atd. Samozřejmě neměly by vyvstat nějaké drastické změny, to má být navržené ze začátku, ale drobnosti se obvykle najdou.
Nepředpokládám, že to někdo dočetl až do konce, pokud ano, asi to bude ještě větší šílenec než já (a to se hned tak nevidí). Přeji vám všem co nejméně nezdokumentovaných a zbastlených projektů, se kterými se budete muset potýkat. Chápu, že ve firmách není často na dokumentaci čas, slyšel jsem hodně argumentů “ale znáte manažery, těm to prostě nevysvětlíte”. Na druhou stranu člověk si musí umět prosadit svou a tím, že strávíte pár hodin psaní dokumentace, ušetříte v budoucnu u většího projektu stovky bugů a chyb, čas nově příchozích lidí, kteří budou projekt studovat a trávit hodiny hledáním, jak se dělá to či ono, a ušetříte si spoustu telefonátů či e-mailů typu “hele pepo, jak se dělalo támhleto?”.
Osobně mě psaní dokumentace nebaví, ale u větších projektů si nedovolím ji neudělat. Hlavně kvůli sobě, po měsíci nebo dvou se každá zmínka o tom, jak to celé dohromady funguje, opravdu hodí.