Nástroje vybírejte podle toho, co potřebujete zachyt
U dávkového vkládání a hromadných aktualizací se často objevuje jiná chyba: aplikace spojí více hodnot do jednoho dotazu a zapomene, že počet parametrů musí odpovídat počtu zástupných symbolů. Pokud se počet neshoduje, vývojář sáhne po ručním skládání a tím vrátí injektáž zpět do hry. Bezpečnější je zpracovat dávku po menších částech nebo použít jeden připravený dotaz v cyklu, i za cenu mírně vyšší režie.
Moderní JavaScript dnes znamená především standard ES6 a novější. Přechod od staršího stylu psaní není jen kosmetická záležitost. Kód je kratší, čitelnější a mnohdy i rychlejší. Zároveň ale přináší nové možnosti, ve kterých se dá snadno udělat chyba. Následující řádky shrnují konkrétní postupy, které se vyplatí používat, a upozorňují na místa, kde vývojáři často klopýtnou.
Základní cyklus má tři kroky a plete se pořád dokola. git status ukáže, co se změnilo. git add soubor přesune změnu do přípravy (staging). git commit -m "popis" ji uloží jako bod v historii. Kdo vynechá git add, diví se, že commit je prázdný. Kdo naopak přidá omylem celý adresář přes git add ., dostane do historie i to, co tam nechce. Zpráva commitu nemá být „oprava" nebo „změny" — za měsíc nebudeš vědět, co se opravovalo. Piš krátce, ale konkrétně: „oprava dělení nulou v exportu".
Příklady musí být spustitelné, ne ilustrativní U každého endpointu uveďte metodu, cestu, parametry v cestě i v query, tělo požadavku a kompletní odpověď včetně hlaviček. Používejte reálná data, ne placeholdery typu "foo" nebo "string". U vnořených struktur ukažte, jak vypadá stav před a po. Pokud endpoint mění stav, přidejte příklad idempotentního volání a vysvětlete, co se stane při opakování. Vyhněte se příkladům, které vrací jen prázdné pole – frontend z nich nepozná tvar dat.
Dobře napsaná zpráva se pozná tak, že při hledání v historii nemusíte otevírat samotný diff. Stačí projít seznam commitů a máte jasno. Zaveďte si jednoduchý zvyk: nejdřív napište, co změna dělá, pak proč, a teprve nakonec zmiňte, jak. Výsledkem je historie, která se dá číst jako deník projektu – a to je při zpětné dohledatelnosti změn ta nejcennější vlastnost.
Před odesláním si zprávu přečtěte nahlas. Pokud z ní nejste schopni do pěti sekund pochopit, co commit dělá, přepište ji. Držte se jednoho jazyka a jednotného času – minulý čas se v některých týmech používá, ale důležitější je konzistence. A nezapomeňte, že commit zpráva není místo pro urážky ani pro interní vtipy; i ty se jednou mohou objevit v oficiálním auditu.
Každý commit v repozitáři je malý záznam o tom, co se změnilo a proč. Pokud zpráva říká jen „oprava" nebo „update", za půl roku nebudete vědět, co se opravovalo ani proč. Cílem není psát romány, ale dodat dost kontextu, aby se změna dala dohledat zpětně – od řádku kódu k důvodu, proč tam je.
Typická chyba je psát zprávu podle sebe, ne podle toho, kdo ji bude číst. Kolega, který za rok hledá, proč se změnilo chování tlačítka, potřebuje vědět, že šlo o opravu chyby na základě hlášení z provozu. Proto se vyplatí uvádět kontext: číslo úkolu, pokud existuje, ale i krátké vysvětlení, co bylo před změnou špatně. Stejně tak je chybou míchat do jednoho commitu refaktoring, opravu chyby a novou funkci – dohledatelnost tím trpí nejvíc.
Nejčastější chyba je dokumentace psaná ručně vedle kódu. Časem se rozejde a nikdo nepozná, která verze platí. Lepší je generovat dokumentaci z anotací nebo ze schématu a udržovat ji jako součást repozitáře. Pokud to nejde, zaveďte pravidlo, že změna endpointu bez úpravy dokumentace neprojde revizí. Verzujte API a v dokumentaci vždy uveďte, které verze se změna týká.
Poslední věc, kterou lidé podceňují, je příklad volání z reálného klienta. Ukažte jeden požadavek odeslaný z prohlížeče nebo z nástroje pro testování, včetně autentizace a hlaviček. Tím se odhalí chybějící CORS, špatně nastavené cookies nebo neočekávané přesměrování. Dokumentace, která se dá zkopírovat a spustit, ušetří víc času než sebelepší popis.
Začněte jednotným formátem odpovědí. Každé volání by mělo vracet stejnou obálku: data, stavový kód, případně seznam chyb. U chyb vždy uvádějte strojově čitelný kód, lidsky čitelnou zprávu a pole, kterého se týká. Vyhněte se tomu, aby jedna chyba vracela řetězec a jiná objekt. Frontend pak nemusí řešit desítky variant a stačí mu jedna funkce pro zpracování odpovědi.
Co do zprávy patří a co naopak škodí Užitečná zpráva odpovídá na tři otázky: co se změnilo, proč to bylo potřeba a jaký to má dopad. Místo „přidal jsem podmínku" napište „přidává kontrolu prázdného vstupu, aby aplikace nespadla při importu bez hlavičky". Vyhněte se odkazům na interní systémové zkratky, kterým po čase nikdo nerozumí, a vynechejte i výrazy jako „různé úpravy" nebo „úklid". Pokud commit obsahuje víc nesouvisejících změn, raději je rozdělte do několika menších – historie pak zůstane čitelná a snadno dohledatelná.