Pečlivá dokumentace zdrojového kódu aneb Dactyl nevykolejí ani erupce na Slunci

Vše začalo sluneční erupcí. Ta vyvolala silnou elektromagnetickou vlnu, která cestovala napříč vesmírem až k čipu umístěnému na desce našeho serverového počítače v Dactylu. Chyba je na světě… kde máme tu dokumentaci?

Nerozhodí nás ani sluneční erupce

*Píp* Co to je za zvuk?

To snad ne! Vlna svým působením zmanipulovala náš čip a zcela mu přenastavila priority. Pomíchala je natolik, že se zničehonic rozhodl oznamovat chybovou hlášku…

„500 Internal Server Error!”

…a to vždy pouze na určitý dotaz.  

„Co se to děje? Tohle se nám přece vůbec nestává!” rozlehlo se naší kanceláří.

A není divu. Všechny naše servery mají stabilní linuxový operační systém. Běží v neustálém provozu (a to dokonce i při aktualizaci samotného operačního systému).

„Jak je možné, že se objevila chyba zrovna teď? To přece nemůže být žádná náhoda,” pomyslel si náš vývojář Štěpán.

Takový problém se jen tak sám nevyřeší restartováním serverové služby, zatímco si odskočíme na teplou kávu dobít baterky. Ne, je třeba rychle jednat a chybu opravit přímo ve zdrojovém kódu! 

Naše pátrání tak může začít.

Na řadu přichází debugování

Z vedení přichází zpráva o chybě a přiložený popis, jak ji reprodukovat. Štěpán je už ale krok napřed a tak přemýšlí, co mohlo chybu zapříčinit. Vypátrat samotný bod zlomu a zjistit, kde dochází k vadě, to přece není až tak složité. 

Hledání nám usnadní šikovné nástroje. Mrkneme se na chybové hlášky s pomocí logů nebo celý kód krůček po krůčku zanalyzujeme.

Problém můžeme přirovant ke špatně smontované skříni. Nejsme zrovna odborníci na montáž nábytku, proto si vždy necháme poradit od profesionála, kde je zapotřebí dotáhnout jaký šroubek.

Naším odborným poradcem je tentokrát debugovací software Xdebug.

Můžeme se do toho pustit… ale počkat, kde máme manuál?

Spásu přináší pečlivá dokumentace kódu

Nač marnit čas a znovu vynalézat kolo, zvláště když takové kolo má tisíce řádků zdrojového kódu. Většinou se jedná o zdrojový kód kolegy nebo třetích stran. Vše máme hotové, hezky pohromadě a nemusíme plýtvat energií. 

Mluvíme o takzvaných knihovnách. Výskyt chyb v knihovnách ale nebývá vůbec běžný a nejčastěji se pojí s nesprávným použitím. 

Ale zpět k našemu problému. Stále potřebujeme přesně zjistit, kde se to pokazilo. Musíme si tak rozebrat, jak celá věc funguje, pochopit ji, zanalyzovat a následně upravit.

Dostáváme se k nedílné součásti psaní zdrojového kódu, a tou je dokumentace. 

Každá funkce, která není úplně triviální, intuitivní a nemůžeme ji na první pohled rozlousknout, by měla obsahovat slovní popis. Programátor s ní pak nemusí složitě zápasit a může se rychle orientovat v konkrétním prostředí… kde zrovna hledáme onu chybu!

Aha! Konečně vidíme, co nám tu nehraje.

Problém jsme našli. Můžeme tak začít vymýšlet, jak chybu opravit nebo jak změnit funkčnosti, aby zapadaly do našeho požadovaného scénáře. S tím nám hravě pomůže právě dokumentace zdrojového kódu.

Napsat kód je jedna věc, ale vyznat se v něm? 

Napsat dobrou dokumentaci ale není žádná legrace. Je důležité, aby byl výsledek hezky ucelený. Můžeme si představit třeba kuchařku, ve které najdeme skvělé a dobře popsané recepty. Jeden je však po babičce, druhý je na asijskou dobrotu a třetí od michelinského kuchaře. 

Taková kuchařka postrádá celistvost a je obtížné se v ní vyznat, nedejbože v ní hledat něco konkrétního.

Stejně tak zdrojový kód musí mít svou strukturu. Každý programátor má však vlastní rukopis a kód píše jinak. Pokud za nás nebude psát robot, tak nemáme šanci takový kód nikdy sjednotit. Abychom si psaní a následné čtení ulehčili, je dobré se držet konvencí. Způsobů psaní je několik a je na každém programátorovi, který si vybere.

Znovu si to předvedeme na naší oblíbené kuchařce. 

U receptu většinou najdeme stejnou strukturu – začíná u surovin, potřebném množství a až poté následuje postup vaření. Samotný průběh je zevrubně popsaný a nesmí například chybět, jestli a jak je potřeba pokrm tepelně upravit, v jakém zařízení, jak dlouho, na kolik stupňů a tak dále.

Čtenář se zkrátka vždy orientuje, v jaké části se zrovna nachází. Může tak jednoduše porovnávat různé recepty a na první pohled ví, kde potřebnou informaci hledat. 

A stejně tak to platí i ve světě programování. Zdrojový kód sice nepřipálíme, ale stále v něm můžeme špatným zacházením nadělat chyby. Konvence tak ve výsledku poslouží programátorovi, aby si chybu uvědomil a následně ji mohl snadno napravit změnou proměnných.

Po důkladné kontrole rovnou do finiše

Co zaručuje dobře napsanou dokumentaci? 

V první řadě je to sám programátor. Nemyslete si, údržba dokumentace a kvalitní struktury zdrojového kódu zabere nějaký ten čas. To neznamená, že si nemůžeme vypomoct. V Dactylu tento krok zčásti automatizujeme pomocí vhodných nástrojů.

Vždy je ale nejlepší ověření od kolegy. Nově přidané segmenty kódu si prochází na produkci kontrolou, takže tím je o to postaráno. Programátoři mnohdy ani nepracují na stejném produktu, a to je dobře. Víc očí víc vidí a rovnou se dozvíme, jestli je náš kód opravdu srozumitelný.

A když něco náhodou přehlédneme, dá nám to pěkně sežrat PHPStan. Pomáhá nám tak dohlížet na správnost kódu, ale také eliminovat chyby a ulevit hardwaru od zbytečné zátěže.

Nebojte se dobré kritiky, díky ní si můžeme předávat cenné zkušenosti.

Mise splněna. Problém jsme pomocí teamworku a moderních technologií našli a efektivně eliminovali. Teď už zbývá jen poslední věc…

Poslední věc?

Ale ne, my si snad nikdy neodpočineme. Co se stalo, ptáte se? Vždy je potřeba něco poštalovat, rozšířit a opravit… neboť ladění kódu je nepřetržitý proces. No nic, zpátky do práce!

Setkali jste se s problémem a restart nepomohl? Brání vám sluneční erupce ve vývoji supermoderní aplikace? Napište nám, my si s tím poradíme za vás!

Tento článek připravil Štěpán Kubičný, náš PHP vývojář.