Osvědčené postupy revize kódu

Autor těží z toho, že získají jiný pohled na svůj úkol a kód. Často se naučí nové triky nebo objeví potenciálně optimálnější způsob řešení určitého problému. Také s jistotou nasadí svou sadu změn, protože vědí, že ostatní lidé zkontrolovali správnost kódu a shodli se, že je vše v pořádku.

Recenzent těží z toho, že vidí různé přístupy k řešení problémů v praxi. Zlepší si také své dovednosti ve čtení kódu, což je velmi důležité, když se ponoří např. do knihovny, která je hodnocena pro použití v projekt. Recenze kódu je také příležitostí k učení pro recenzenta stejně jako pro autora: může se naučit i nové triky.

Na stránkách tým jako celek, protože přezkoumání řešení určitého problému vyžaduje pochopení problému alespoň na vysoké úrovni abstrakce. To pomáhá odbourávat náhodná znalostní sila, která se mohou v týmu vyskytnout. Zvýší se také "faktor sběrnice": protože o dané změně vědí alespoň dva lidé (nejlépe více), je menší pravděpodobnost, že nastane situace, kdy nikdo z týmu nebude vědět, jak modul aktualizovat, nebo proč se může vyskytovat určitá chyba.

Zákazník výhody rychle a s jistotou zavedených změn a řešení. Společně s dalšími osvědčenými postupy (jako je velké pokrytí testů, CI/CD, stagingová prostředí atd.) zajišťují revize kódu také to, že nasazené řešení je bezpečné, rozumné a splňuje zadané požadavky.

Záměr a použití těchto pokynů

Nezapomeňte, že tyto návrhy mají především vytvořit prostředí, které bude příznivé pro ambiciózní a efektivní řešení problémů, a zároveň vytvořit záchrannou síť a podpořit důvěru a transparentnost u každého člena týmu.

Ačkoli se důrazně doporučuje, aby tým tyto pokyny dodržoval, nejsou zamýšleny jako pevná pravidla. Tento rámec také není zamýšlen jako "proces", který je třeba přesně dodržovat, protože rigidní procesy mají tendenci snižovat rychlost a podporovat plýtvání.

Tyto pokyny můžete v rámci svého týmu dále rozvíjet. Nezapomeňte však, že když se vývojáři střídají mezi týmy, budou očekávat, že kontrola kódu v každém týmu, ke kterému se připojí, bude stále vycházet z tohoto dokumentu. Veškerá další pravidla si nechte zdokumentovat a zpětně do tohoto dokumentu přispívejte vylepšeními, která se výjimečně osvědčila.

Odpovědnosti spojené s revizí kódu

Každý člen týmu má v souvislosti s revizí kódu určité povinnosti. Níže jsou uvedeny určité zásady "co dělat" a "co nedělat" při revizi kódu podle rolí v procesu.

Vedoucí projektu

• DO zajistěte, aby byly vaše repozitáře dobře nakonfigurovány (např. sloučení do vaší produkční větve není povoleno bez alespoň jedné schvalovací revize).
• DO zajistěte, aby váš tým těmto postupům rozuměl a uplatňoval je, a aktivně se snažte podporovat porozumění tomu, proč děláme věci určitým způsobem.
• DO dávejte pozor na nerozhodné situace, kdy nelze vyřešit protichůdné názory: jako technický vedoucí svého týmu jste zodpovědní za to, abyste v takových případech zvolili vhodnější řešení a pokračovali v práci.
• Nicméně, NEDĚLEJTE TO používat vedení projektu jako tupý nástroj. NEDĚLEJTE TO "pull rank". DO uvítejte recenze a kritiku svých řešení stejně tak, jako je podporujete u práce kohokoli jiného.
• UVAŽUJTE o přidání integrace služby GitHub do kanálu Slack vašeho týmu. Může to být užitečné, aby se požadavky na recenze lépe dostaly do hledáčku recenzentů, ale v závislosti na celkovém objemu vašeho kanálu to může, ale nemusí být pro váš tým vhodné.

Člen týmu

• Zúčastněte se recenzí kódu. Není přijatelné, abyste kód nepřezkoumávali.
• NEZAPOMEŇTE provádět revize kódu: vaši kolegové jsou závislí na tom, jak pokročíte v jejich práci!
• Pokud určitou recenzi rozhodně nemůžete provést, DO jasně a otevřeně ji sdělit.
• Nicméně, NEDĚLEJTE TO předpokládat, že nemůžete provést určitou revizi, protože neznáte daný modul/část systému/ specifikaci obchodní logiky. Revize kódu je důležitou příležitostí k učení.
• Pokud máte pocit, že o něčem nevíte dost, abyste mohli napsat recenzi, DO zeptejte se na to autora: jistě vám rád vysvětlí, k čemu mají změny sloužit.
• NEDĚLEJTE TO odepřít hodnocení na základě úrovně zkušeností (vaše) nebo autora).
• DO snažte se zkontrolovat alespoň tolik PR, kolik jich vytvoříte. V ideálním případě udržujte poměr počtu recenzí k počtu požadovaných recenzí nad 1 (zejména ve větších týmech).

Autor

• DO pochopit, že je vaší odpovědností nechat si kód zkontrolovat - váš tým může aktivně vyhledávat žádosti o revizi, ale nemusí.
• NEDĚLEJTE TO zadávejte/požadujte recenze vždy od stejných členů týmu - budete mít větší prospěch z různorodých recenzentů (a naopak, z recenze vašeho kódu bude mít prospěch širší okruh vývojářů).
• NEDĚLEJTE TO vyloučit někoho z přezkumu na základě zkušeností. Mladší vývojáři mají z přezkoumání kódu prospěch. Starší vývojáři mají z přezkoumání kódu prospěch. Jak je uvedeno v předmluvě k tomuto dokumentu, všichni přínosy z revize kódu.
• UPOZORNĚNÍ: výběr recenzentů pomocí náhodného výběru. Např. v Ruby, %w[teammate1 teammate2 teammate3].sample dokáže zázraky.
• DO přiřadit k požadavkům na stažení alespoň dva recenzenty, pokud to není absolutně nemožné. Tímto způsobem bude mít z procesu prospěch více lidí (a ve třech lidech je těžší dospět k nerozhodnému výsledku).
• DO reagujte na požadavky na stažení. I když byste neměli přerušit svůj tok a reagovat na všechny připomínky hned, ujistěte se, že vaše odpovědi jsou včasné - jinak se vaše PR budou zdržovat v revizi kódu donekonečna.
• DO přinést otevřený přístup. Vždy předpokládejte, že se vám recenzent snaží pomoci s těmi nejlepšími úmysly. Vysvětlete svou logiku, zabývejte se argumenty recenzenta a odpovídejte na jeho otázky.
• DO být zdvořilý. Nedorozumění se stávají, ale nemusí se vymknout kontrole a poškodit atmosféru v týmu.
• DO být upřímný. Pokud se domníváte, že je to nejlepší řešení, řekněte to a předložte své argumenty. Pokud se přesvědčíte, že návrhy recenzenta jsou lepší než to, co jste vytvořili, řekněte mu to. Pokud si myslíte, že lze vytvořit "nejlepší řešení z obou světů" s využitím vašich i recenzentových nápadů, navrhněte mu ho. Nakonec se ve svých žádostech o stažení snažte dosáhnout konsensu.
• DO nechte řešení jejich připomínek na recenzentovi - neřešte je jen proto, že jste přesvědčeni, že už je to v pořádku.
• DO aktivně vysvětlovat recenzentům svůj úkol, své zdůvodnění a další požadavky. Je v pořádku, že nevíte - není přijatelné znalosti zatajovat.
• NEDĚLEJTE TO předpokládat, že víte všechno - všichni jsme úžasní odborníci, ale je důležité, abyste do práce s vámi vnášeli určitou dávku pokory.
• DO být prvním recenzentem vašeho kódu. Nasaďte si čepici recenzenta a pečlivě kód prohlédněte, jako byste to udělali u člověka, kterého většinou nemáte rádi. Identifikujte a odstraňte většinu zjevných věcí, jako jsou prázdné řádky, případné zbytky nebo chybějící specifikace. Nic nevynechávejte - stejně na to bude s největší pravděpodobností upozorněno. Neplýtvejte časem recenzentů!
• DO důkladně popište svůj požadavek na stažení. Popis je dobrý, když recenzenta při čtení kódu nic nepřekvapí. Nezapomeňte, že nemůže číst vaše myšlenky. Proto je důležité popsat věci, které nejsou zřejmé, klíčová rozhodnutí s odůvodněním nebo všechny nové třídy a soubory.
• UPOZORNĚNÍ: pomocí šablony žádosti o stažení. Pokud používáte Github, přidejte ji do svého úložiště pod položkou .github/pull_request_template.md. Vyzývá všechny členy týmu, aby popsali své požadavky na stažení. Je také mnohem snazší psát, když máte pole popisu vyplněné šablonou. Zde najdete šablonu, kterou používáme v jednom z našich projektů https://gist.github.com/weemanjz/a20ccb9f3f492b9bd21ab026a1d46353

Autor

• DO pochopit, že je vaší odpovědností mít své revize kódu - váš tým může aktivně vyhledávat žádosti o revizi, ale nemusí.
• NEDĚLEJTE TO vždy přiřadit/vyžádat si recenze od stejného recenzenti kódu - budete mít větší užitek z pestré skupiny recenzentů (a naopak, širší okruh vývojářů bude mít užitek z recenzování vašeho kódu).
• NEDĚLEJTE TO vyloučit někoho z přezkumu na základě zkušeností. Mladší vývojáři mají prospěch z provádění recenze kódu. Starší vývojáři mají prospěch z provádění recenze kódu. Jak je uvedeno v předmluvě k tomuto dokumentu, všichni výhody z provádění recenze kódu.

Recenzent

• DO používat jazyk návrhů namísto požadavků. Místo toho, abyste říkali "Měl bys zlepšit kvalitu kódu tím, že místo toho uděláte X", řekněme "Uvažovali jste o zlepšení kvalita kódu tím, že děláte X?"
• DO vysvětlete své návrhy. "Myslím si, že X je zde lepší, protože pomáhá při přenos znalostí a zlepšení kvality kódu."
• I když váš návrh pochází z objektivních zdrojů (např. kódový styl pokyny), DO požádat autora, aby něco udělal, místo toho, aby mu to řekl. "Udržujte prosím všechny widgety frobnicated podle našeho kódový styl průvodce - [odkaz]"
• NEDĚLEJTE TO předpokládat, že víte všechno. "Chápu to tak, že tento widget by nikdy neměl frobnikovat, a za těchto podmínek se tak stane - je to výjimka, která potřebuje výjimku? revize kódu?"
• DO používat inkluzivní jazyk. "Myslím, že bychom na tom byli v budoucnu lépe, kdybychom to takto postavili. Co si o tom myslíte? lepší kontrola kódu návrh?" a "Možná bychom měli místo toho použít X pro účinná revize kódu?"
• DO být rychlý při plnění svých úkolů recenze kódu. Neměli byste kvůli nim přerušovat svůj tok, ale snažte se udržet smyčku těsnou, pokud je to možné. Někteří lidé je rádi dělají buď na začátku, nebo na konci svého pracovního dne, buď jako "zahřátí", nebo "ochlazení".

Upozorňujeme, že tato klíčová slova byla vložena tak, aby byl zachován kontext a soudržnost textu. Pokud si je přejete na konkrétních místech, laskavě je uveďte.