Cvičení na kontrolu kódu: jak využít vzájemné hodnocení k rozvoji analýzy a technického úsudku

Vývojář otevře pull request, který přidá výpočet slevy do pokladní služby. Testy projdou a rozdíl je krátký. Recenzent jej schválí během dvou minut s kódem „LGTM“. O tři měsíce později potřebuje kolega změnit stejnou funkci a zjistí, že na jednom místě kombinuje pravidla pro tvorbu cen, zaokrouhlování a přístup k databázi. Nikdo nemůže s jistotou říct, co smí dělat.

Toto je ilustrativní scénář, nikoli zdokumentovaný incident. Ukazuje, co musí vzájemné hodnocení kódu přinést, když funguje jako učební aktivita: recenzenta, který dokáže vidět věrohodnou změnu, odhalit problém, který ještě není chybou, a vysvětlit ho způsobem, na který může autor reagovat.

Tato příručka je určena pro vedoucí inženýrských oddělení a manažery inženýrských oddělení. Ukazuje, jak navrhovat cvičení pro kontrolu kódu které tuto dovednost budují záměrně, místo aby doufali, že si ji recenzenti vezmou z fronty. Zahrnuje problém s výkonem, mezery, které je třeba diagnostikovat, jak strukturovat přípravu a procvičování, jeden praktický příklad a jak ověřit, zda se dovednost přenáší do skutečných recenzí. Nechte si od vedoucích inženýrů ověřit každý případ, vadu a kritérium, než je použijete.

Co jsou to cvičení pro kontrolu kódu?

Cvičení s revizí kódu jsou strukturované praktické úkoly, ve kterých vývojář kontroluje připravenou změnu, vysvětluje, co zjistil a proč je to důležité, a získává zpětnou vazbu ke kvalitě tohoto vysvětlení. Liší se od kontrol, které váš tým provádí každý den. Změna je vybrána předem, její obavy jsou známy a cílem je vylepšit kontrolora, spíše než změnu odeslat.

Rychlá fakta

1. Popište problém s výkonem

Začněte úkolem, jednou větou: v případě změny recenzent vysvětlí, co zjistil, proč je to důležité a co s tím autor může udělat. Důležité slovo je „vysvětlit“. Odhalení problému je polovina dovednosti. Řeknout to tak, aby to kolega s jiným názorem mohl pochopit, zvážit to a jednat, je druhá polovina.

Výzkum moderní revize kódu podporuje pohled nad rámec hledání chyb. Ve studii společnosti Microsoft Bacchelli a Bird pozorovali, dělali rozhovory a zkoumali vývojáře a manažery. Zjistili, že hledání defektů je stále hlavní motivací pro revizi, ale že revize se týkaly defektů méně, než lidé očekávali. Přinášely také další výhody, jako je sdílení znalostí, povědomí o týmu a alternativní řešení, a vědci popsali porozumění kódu a změnám jako klíčový aspekt revize (Bacchelli a Bird, ICSE 2013). Jedná se o studii týmů jedné společnosti, takže ji použijte jako důvod k návrhu pro pochopení, ne jako sazbu pro ten váš.

Zveřejněný standard pro recenze společnosti Google ukazuje stejným směrem. Říká recenzentům, aby upřednostnili schválení změny, jakmile jednoznačně zlepší celkový stav kódu, i když není dokonalý, a říká, že recenze může vývojáře něco nového naučit, takže komentáře, které někomu pomohou se učit, jsou vítány (Google Engineering Practices). Oba zdroje popisují přezkoumání jako místo, kde se uplatňuje a předává úsudek. To je to, co by si vaše cvičení měla procvičovat.

2. Diagnostikovat mezery ve vzdělávání a kontextu

Porovnejte úkol s tím, co váš současný program procvičuje a hodnotí.

1. Využívá současná praxe skutečný úkol? Pokud se noví recenzenti učí čtením stylistického průvodce a následným prohlížením živých pull requestů, procvičují si práci na skutečném projektu bez bezpečného místa, kde by se mohli mýlit. Pokud je hodnocení kvízem o etiketě recenze, měří zapamatování si pravidel, nikoli schopnost je aplikovat na změnu.
2. Jaká je kognitivní poptávka? V revidované Bloomově taxonomii se posuzování, zda je návrh dobrý, a zvažování jeho kompromisů nachází na úrovni analýzy a hodnocení a navrhování lepší struktury dosahuje úrovně tvorby. Pokud se vaše cvičení ptají pouze na „co tento kód dělá?“, zastaví se u pochopení. Náš průvodce přiřazování vzdělávacích aktivit k Bloomově taxonomii ukazuje, jak přizpůsobit aktivitu úrovni.
3. Stojí v cestě něco jiného než dovednost? Zkontrolujte dobu kontroly, nástroje, odpovědnost a normy týmu. Pokud mají recenzenti pět minut na jeden pull request, žádné cvičení nevede k promyšlenému vysvětlení. Pokud autoři berou každý komentář jako kritiku, recenzenti zmírní svá zjištění, dokud neřeknou nic. Nahlaste tyto příčiny lidem, kteří je mohou napravit.

3. Příprava návrhu, praxe a zpětná vazba

Každé fázi přidělte samostatný úkol.

Příprava. Než začnou, zkontrolujte, co recenzenti potřebují: kontrolní seznam týmu pro kontrolu, principy návrhu, na kterých se tým opírá, a jak číst rozdíly ve vašich nástrojích. Udržujte si vlastní tempo a stručnost. Kontrola odvolání potvrzuje pouze předpoklady a není důkazem, že by někdo mohl kontrolovat.

Praxe. Použijte připravené změny s malým počtem základních problémů různého druhu: chyba v korektnosti, problém s udržovatelností, jako je smíšená odpovědnost v úvodním příkladu, nejasný název nebo chybějící test a nějaký kód, který je v pořádku. Požádejte recenzenta, aby napsal komentář, který by zanechal, seřadil problémy a uvedl, jaké další informace by chtěl. Praktická lekce CodeRefinery ukazuje, jak to funguje: lidé otevřou žádost o změnu obsahující malou překlep a větší chybu a poté ji zkontrolují jako kolegové (CodeRefinery, Procvičování kontroly kódu). Vytvořte si svůj vlastní z vlastní kódové základny, aby konvence a kompromisy byly reálné.

Zpětná vazba. Propojte to s rozhodnutími, která recenzent učinil. „Všimli jste si problému se zaokrouhlováním, ale váš komentář napsal ‚to vypadá špatně‘, aniž byste uvedli, jaký vstup problém porušuje“ je užitečnější než „nalezeno 2 ze 4“.

Živý vstup nebo asynchronní recenze? Živý vstup je nejcennější, když je problém nejednoznačný a recenzenti se učí z toho, jak vedoucí inženýr říká, proč by ho měli vznést, nebo proč by ho měli nechat být. Asynchronní kontrola je dostatečná pro porovnání komentářů s anotovaným expertním posudkem.

4. Vypracujte realistický příklad

Ilustrativní příklad. Vedoucí inženýrství by měl před použitím ověřit případ a kritéria odpovědi.

Pouzdro. Změna přidá výpočet slevy do pokladní služby. Projde testy. V jedné funkci aplikuje procentuální a fixní slevy, zaokrouhlí výsledek, zapíše do databáze a odešle událost. Má jeden test, pro jednoprocentní slevu.

Úkol. Recenzent zapíše komentáře, které by zanechali, seřadí jejich připomínky a sdělí, co by potřebovali vědět před schválením.

První pokus. „Vypadá to dobře, test prošel. Možná to rozdělit?“ Recenzent si něčeho všiml, ale neřekl čeho, proč je to důležité ani co má dělat. Autor s tím nemůže nic dělat.

Zpětná vazba a opakování. Moderátor se ptá: co by v budoucnu mohlo vést k narušení funkce? Co byste požádali autora, aby doplnil před schválením? Opakovaný pokus požaduje konkrétní komentář ke každému problému s uvedením důvodu a návrhu.

Silnější pokus. „Funkce aplikuje dva druhy slev, zaokrouhluje, ukládá a publikuje událost, takže změna zaokrouhlování by mohla změnit to, co ukládáme a co publikujeme zároveň. Požádal bych, aby se pravidla pro stanovování cen přesunula do čisté funkce, kterou můžeme testovat samostatně. Jediný test zahrnuje pouze procentuální slevu. Požádal bych o pevnou slevu a objednávku, která vynuluje celkový součet. Nejsem si jistý, zda se má událost spustit, když je celkový součet nulový, takže bych se zeptal autora.“ Všimněte si, že tento komentář pojmenuje problém, uvádí důvod, předkládá konkrétní návrh a uvádí, co recenzent neví.

5. Posouzení kapacit a plánování přenosu

Důkazem schopnosti je výkon u nové změny, kterou hodnotitel neviděl. Ohodnoťte přesnost zjištění a užitečnost vysvětlení. Jednoduchá rubrika používá stupnici od 0 do 2 pro každé kritérium:

Kotvy: 0 znamená chybějící nebo nepodložené, 1 znamená částečné s relevantními opomenutími a 2 znamená úplné a odůvodněné podle dohodnutých kritérií. Kritické chyby definujte samostatně, například schválení změny s rizikem ztráty dat, aby dobré celkové skóre nemohlo žádné riziko zakrýt. Kritéria upravte s technickým manažerem; tato rubrika je výchozím návrhem, nikoli validovaným standardem připravenosti. Více informací o zdůvodnění bodování naleznete v našem průvodci navrhování interaktivních postupů s užitečnou zpětnou vazbou.

Naplánujte si převod. Po cvičení zkontrolujte o několik týdnů později vzorek skutečných recenzí od recenzenta s použitím stejných kritérií. Porovnejte s výchozím stavem zjištěným před školením a předem definujte populaci a načasování. Před započítáním výsledků cvičení se podívejte na další změny, ke kterým došlo ve stejném období, jako je nový nástroj pro hodnocení nebo změna personálního obsazení.

6. Cvičení můžete provádět živě nebo vlastním tempem s AhaSlides

Cvičení můžete provést na workshopu nebo nechat recenzenty, aby si s ním prošli sami. V živém vystoupení ukažte připravenou změnu a pro diskusi použijte interaktivní snímky:

1. Vyberte odpověď na otázku „Kterou obavu byste vznesli jako první?“ s možnostmi uvedených obav. Před zveřejněním svého vlastního pořadí ukažte rozptyl.
2. Open Ended například „napište komentář, který byste zanechali“. Recenzenti mohou porovnat své formulace s formulacemi ostatních, a zde se projeví jejich dovednost vysvětlování.
3. Stupnice hodnocení na otázku „jak závažné je to?“, aby skupina mohla vidět, kde se úsudky liší, a prodiskutovat proč.

Pro recenzenty, kteří se nemohou zúčastnit, lze stejnou sekvenci použít vlastním tempem, s anotovanou odbornou recenzí zobrazenou po každé odpovědi. Jakékoli tvrzení o provádění kódu, integracích nebo funkcích umělé inteligence považujte za nepotvrzené, dokud si ho nevyzkoušíte s vlastním materiálem.

Pokud také školíte recenzenty v oblasti kódu psaného pomocí umělé inteligence, podívejte se na naši doprovodnou příručku na Školení pro kontrolu kódu generovaného umělou inteligencíTenhle příspěvek je o auditu generovaných výstupů. Tenhle je o tom, jak si lidé navzájem kontrolují práci a jak vysvětlují, co zjistili.

Omezení, která mohou přetrvávat

• Čas na kontrolu. Promyšlený komentář trvá déle než „LGTM“ a termíny se posouvají spíše ke kratší verzi.
• Týmové normy. Pokud je zpětná vazba vnímána jako osobní kritika, recenzenti svá zjištění zmírní nebo je upustí.
• Krytí případu. Jedno cvičení ukazuje několik druhů obav. Hodnocení nepopisuje úsudek recenzenta obecně.
• Převod. Výkon v dílně není totéž jako výkon v rušné frontě, proto si ověřte i skutečné recenze.

Včas je pojmenujte sponzorům a naplánujte si samostatné opravy. Cvičení zlepšují to, co recenzent může vidět a vysvětlit. Nevytvářejí čas ani normy.

Často kladené otázky

Co jsou to cvičení pro kontrolu kódu?

Jsou to připravené praktické úkoly, ve kterých vývojář zhodnotí změnu se známými výhradami, zapíše komentáře, které by zanechal, a získá zpětnou vazbu ohledně přesnosti a užitečnosti. Cílem je rozvíjet dovednosti recenzenta, nikoli změnu odeslat.

Jak hodnotíte, zda se zlepšil úsudek recenzenta?

Uveďte novou změnu, kterou neviděli, a ohodnoťte zjištění a vysvětlení podle dohodnutých kritérií. Poté o několik týdnů později zkontrolujte vzorek skutečných recenzí. Kvíz o pravidlech pro hodnocení potvrzuje pouze předpoklady.

Je peer code review hlavně o hledání chyb?

Hledání vad je stále hlavní motivací, ale jedna studie v Microsoftu zjistila, že recenze se méně zaměřovaly na vady, než se očekávalo, a zároveň vedly ke sdílení znalostí a povědomí týmu. Navrhujte cvičení, která odměňují vysvětlení a pochopení, stejně jako počet vad.

Kde začít

Vyberte si jeden druh změny, kterou váš tým často kontroluje. Napište prohlášení o výkonnosti, požádejte vedoucího inženýra, aby připravil jednu změnu se třemi nebo čtyřmi základními obavami, a vypracujte tříkritériovou rubriku se stupnicí od 0 do 2 a seznamem kritických chyb. Otestujte ji v malé skupině a poté porovnejte jejich další reálná hodnocení s výchozím stavem.

Chcete-li vidět, jak by se dalo cvičení s revizí spustit živě s vaším vlastním týmem a následně jej znovu použít vlastním tempem, prozkoumejte AhaSlides.