Slovník pojmů

Code review

Code review je spolupráce autora a reviewera nad konkrétní změnou. Automatizace najde opakovatelné chyby; člověk ověřuje, zda změna dává smysl v produktu, doméně a provozu.

Stručná definice

Před merge se nekontroluje jen kód, ale i rozhodnutí v něm.

Code review neznamená hledání překlepů ani soutěž, kdo zná více zkratek. Autor vysvětlí problém, zvolený postup, riziko a způsob ověření. Reviewer čte změněný diff, související kód a případně chování aplikace, aby mohl dát užitečnou zpětnou vazbu před mergem pull requestu.

CI, statická analýza a automatizované testy jsou důležitá gate. Ověřují pravidla, která lze popsat a opakovat. Neznají ale automaticky obchodní záměr, srozumitelnost pro dalšího vývojáře, vhodnost změny datového toku ani to, zda nová funkce neporuší důležitý scénář zákazníka.

Pojem se někdy překládá jako revize kódu nebo kontrola změny. Je širší než komentář ke konkrétnímu řádku: dobré review zahrnuje i popis změny, rozsah diffu, testy, bezpečnostní a provozní dopad. Nejde však o formální audit, který by sám garantoval bezchybnost nebo bezpečnost celé aplikace.

K čemu slouží

Sdílené porozumění změně před tím, než se stane součástí produktu

Dobré review má přiměřený rozsah a jasný cíl. Reviewer není pasivní schvalovací razítko a autor nemusí každou připomínku bez diskuse přijmout.

ověření, že změna odpovídá zadání, zvolenému řešení a hranicím systému
nalezení chyb v okrajových scénářích, které test nepokrývá nebo neumí snadno vyjádřit
kontrola práce s oprávněními, citlivými daty, chybami, retry a dopady na provoz
společné ujasnění názvů, odpovědností tříd a veřejných kontraktů
sdílení znalosti o části systému, aby nebyla uzavřená u jediného autora
záznam rozhodnutí a důvodu výjimky pro budoucí údržbu

Praktický příklad

Webhook platby vypadá krátce, ale nese důležité otázky

Webhook po přijetí platby nemá jen změnit stav objednávky. Reviewer se zeptá, zda je ověřený podpis, zda objednávka patří do správného kontextu a co se stane při duplicitním doručení. Idempotence je zde business požadavek, který lint ani zelený build automaticky nedokážou potvrdit.

Užitečný komentář je konkrétní a vysvětluje riziko: „Může poskytovatel poslat stejný event znovu? Pokud ano, potřebujeme uložit jeho ID před změnou stavu, jinak odešleme dva doklady.“ Neříká jen „tohle je špatně“, ale umožní autorovi ověřit předpoklad a najít odpovídající řešení.

PHP

public function paymentWebhook(Request $request): Response
{
    $event = json_decode($request->getContent(), true);
    $order = $orders->get($event['orderId']);

    $order->markPaid();
    $orders->save($order);

    return new Response('', 204);
}

Jak review probíhá

Od srozumitelného záměru k vědomému rozhodnutí o merge

Textový diagram: autor → popis a diff → automatické kontroly → reviewer → připomínky či approval → opravená změna → merge.

Autor připraví změnu Rozdělí práci do čitelného diffu, popíše problém, řešení, testy, omezení a případný plán vydání.
Automatizace dá rychlou zpětnou vazbu CI spustí lint, testy a statickou analýzu. Selhání je podklad k opravě, ne práce pro reviewera, aby je ručně přepisoval.
Reviewer si nejdřív přečte kontext Porovná zadání, popis a diff. Teprve potom hodnotí jednotlivé řádky, pojmenování a implementační detail.
Komentáře vedou k rozhodnutí Komentář může být otázka, návrh nebo blokující problém. Autor odpoví, opraví kód nebo společně s reviewerem zdokumentuje, proč je řešení přiměřené.
Approval nebo requested changes Approval říká, že reviewer v daném rozsahu nevidí překážku k merge. Requested changes označuje problém, který má autor vyřešit a nechat znovu ověřit podle pravidel týmu.

Co review skutečně kontroluje

Diff, kontext a riziko jsou důležitější než počet komentářů.

Ne každá připomínka má stejnou závažnost. Tým si má umět odlišit blokující problém od dobrovolného návrhu nebo otázky k pochopení.

Diff a rozsah změny

Reviewer ověřuje, že diff řeší popsaný problém a nepřidává nesouvisející refaktoring. Malý logický celek se chápe, testuje i vrací snáz než jedna velká směs změn.

Autor a reviewer

Autor nese odpovědnost za srozumitelný návrh a reakci na feedback. Reviewer nese odpovědnost za pečlivou kontrolu v přiměřeném čase, ne za převzetí implementace nebo vlastnictví celé změny.

Komentář, approval a requested changes

Komentář může jen sdílet pozorování. Approval není globální certifikace kvality. Requested changes má být jasné, věcné a navázané na riziko; jeho účinek na možnost merge určuje nastavení platformy a chráněné větve.

Automatizace a lidský úsudek

PHPStan, testy a CI odhalují opakovatelné porušení kontraktu. Reviewer řeší například nejasný datový vlastník, špatně zvolenou hranici transakce, chybějící fallback nebo nevhodné API pro klienta.

Bezpečnost a oprávnění

Autentizace určuje, kdo se přihlásil; autorizace určuje, co smí udělat. Review kontroluje obě hranice, práci se secrets, validaci nedůvěryhodných vstupů i to, zda log neobsahuje citlivé údaje.

Business a provozní relevance

Změna statusu objednávky, ceny nebo skladu může být technicky čistá a přesto špatná. Reviewer ověřuje předpoklady, souběh, chybové stavy, metriky, migraci dat a dopad při částečném selhání.

Výhody a limity

Druhá sada očí pomáhá, ale nenahrazuje odpovědnost ani testování.

Přínosy

chyba a nejasný předpoklad se mohou objevit před merge
sdílená znalost o kódu a doméně snižuje závislost na jednom autorovi
konzistentnější kontrakty, názvy a hranice komponent
dohledatelné rozhodnutí u rizikové nebo neintuitivní změny

Časté chyby

schvalovat bez přečtení diffu jen proto, že je CI zelené
soustředit review na osobní styl a ztratit business či bezpečnostní riziko
poslat příliš velký nebo nesouvisející diff, který nikdo nemůže pečlivě přečíst
nechat blokující komentář bez vysvětlení, priority a následného ověření
považovat approval za produkční deploy nebo záruku, že se chyba nemůže objevit

Kdy dává smysl

Pro každou změnu, jejíž dopad stojí za druhé porozumění.

Review se vyplatí od malé opravy po kritickou změnu platby. Hloubka review má odpovídat riziku: oprava překlepu nepotřebuje stejný proces jako migrace objednávek, změna oprávnění nebo napojení na poskytovatele platby. Naléhavá oprava může mít zkrácený postup, ale pořád potřebuje dohledatelný důvod a následné ověření.

Review není vhodné používat jako jediný způsob koordinace rozsáhlého nejasného úkolu. Nejdřív je potřeba vyjasnit zadání, architekturu nebo experiment v menším kroku. Pull request pak ukazuje proveditelnou změnu, ne nahrazuje všechny produktové schůzky.

Praktická pravidla

Připravit review tak, aby pomohlo rychle a věcně.

Kvalitní review začíná ještě před odesláním žádosti o kontrolu.

autor uvede problém, řešení, testy, omezení, riziko dat a případný rollout či rollback
diff držet malý, logicky sourodý a bez nesouvisejícího formátování
reviewer nejdřív čte popis a hlavní tok, potom detail jednotlivých řádků
u blokující připomínky popsat dopad, očekávané chování nebo otázku, kterou je třeba vyřešit
po změně kódu znovu spustit relevantní CI a vyžádat re-review, když to vyžaduje pravidlo týmu
neobcházet povinný approval ani ochranu větve bez dohledatelného důvodu a odpovědnosti

Časté otázky

Review bez zbytečných záměn

Nahrazuje code review CI a statickou analýzu?

Ne. CI, testy a statická analýza hledají opakovatelné chyby. Code review přidává lidské porozumění záměru, kontextu, riziku a obchodnímu dopadu.

Je approval záruka, že kód je bez chyby?

Ne. Je to rozhodnutí reviewera nad konkrétním rozsahem změny a dostupným kontextem. Testy, monitoring a odpovědnost autora zůstávají potřeba.

Musí se opravit každý komentář?

Ne nutně. Autor a reviewer mají dojít k jasnému rozhodnutí. Blokující problém se opraví nebo vědomě eskaluje; doporučení lze odložit, pokud je důvod zaznamenaný a tým s ním souhlasí.

Má reviewer změnu přepsat za autora?

Obvykle ne. Reviewer má vysvětlit riziko, otázku či směr zlepšení. Převzetí implementace dává smysl jen výjimečně, například při párové práci nebo naléhavém incidentu.

Jak pracuji s kvalitou

Review propojuji s testy, statickou analýzou a srozumitelnou odpovědností za změnu.

Kvalita vzniká v běžném workflow: malý diff, automatizované kontroly, věcná zpětná vazba a ověření dopadu po merge.

Zobrazit zkušenosti s testováním a kvalitou Nezávazně probrat projekt

GitHub Docs: Pull request reviews