Vývojár otvorí pull request, ktorý pridá výpočet zľavy do pokladničnej služby. Testy prebehnú úspešne a rozdiel je krátky. Recenzent ho schváli za dve minúty pomocou „LGTM“. O tri mesiace neskôr musí kolega zmeniť tú istú funkciu a zistí, že na jednom mieste mieša pravidlá stanovovania cien, zaokrúhľovania a prístupu k databáze. Nikto nemôže s istotou povedať, čo je povolené robiť.
Toto je ilustratívny scenár, nie zdokumentovaný incident. Ukazuje, čo musí vzájomné hodnotenie kódu priniesť, keď funguje ako vzdelávacia aktivita: recenzent, ktorý dokáže vidieť hodnovernú zmenu, odhaliť problém, ktorý ešte nie je chybou, a vysvetliť ho spôsobom, na základe ktorého môže autor reagovať.
Táto príručka je určená pre vedúcich pracovníkov v oblasti inžinierskych aktivít a manažérov inžinierstva. Ukazuje, ako navrhovať cvičenia na kontrolu kódu ktoré budujú danú zručnosť zámerne, namiesto toho, aby dúfali, že si ju recenzenti vyberú z radu. Zahŕňa problém s výkonom, nedostatky, ktoré treba diagnostikovať, ako štruktúrovať prípravu a precvičovanie, jeden praktický príklad a ako skontrolovať, či sa zručnosť prenáša do skutočných recenzií. Pred použitím nechajte vedúcich inžinierov overiť každý prípad, chybu a kritérium.
Čo sú to cvičenia na kontrolu kódu?
Cvičenia na kontrolu kódu sú štruktúrované praktické úlohy, v ktorých vývojár kontroluje pripravenú zmenu, vysvetľuje, čo zistil a prečo je to dôležité, a získava spätnú väzbu o kvalite tohto vysvetlenia. Líšia sa od kontrol, ktoré váš tím robí každý deň. Zmena je vybraná vopred, jej obavy sú známe a cieľom je zlepšiť recenzenta, a nie zmenu odovzdať.
Rýchle fakty
| Otázka | Stručná odpoveď |
|---|---|
| Aká je úloha? | Vysvetlite zistenia recenzie a poskytnite spätnú väzbu, na základe ktorej môže autor konať. |
| Aké skóre dosiahnete? | Presnosť zistení a užitočnosť vysvetlenia. |
| Stačí počítať chyby? | Nie. Recenzie sú o viac než len o chybách, takže cvičenie, ktoré odmeňuje iba počet chýb, trénuje nesprávny návyk. |
| Aký je kognitívny dopyt? | Analyzujte a vyhodnoťte návrh a potom vytvorte lepší návrh. |
| Kto prípad potvrdí? | Manažér inžinierstva alebo vedúci inžinier, ktorý vlastní kódovú základňu. |
| Čo cvičenia nedokážu vyriešiť? | Čas na preskúmanie, nejasné vlastníctvo a tlak na rýchle zlúčenie. |
| Ako vieš, že to fungovalo? | Nová, nevídaná zmena preskúmaná podľa dohodnutých kritérií a následné kroky na základe skutočných recenzií. |
1. Popíšte problém s výkonom
Začnite s úlohou, jednou vetou: v prípade zmeny recenzent vysvetlí, čo zistil, prečo je to dôležité a čo s tým autor môže urobiť. Dôležité slovo je „vysvetliť“. Všimnúť si problém je polovica zručnosti. Povedať to tak, aby to kolega s iným názorom pochopil, zvážil a konal, je druhá polovica.
Výskum modernej kontroly kódu podporuje pohľad za hranice hľadania chýb. V štúdii v spoločnosti Microsoft Bacchelli a Bird pozorovali, robili rozhovory a prieskumy medzi vývojármi a manažérmi. Zistili, že hľadanie chýb je stále hlavnou motiváciou pre kontrolu, ale kontroly sa týkali menej chýb, ako ľudia očakávali. Priniesli aj ďalšie výhody, ako je zdieľanie znalostí, povedomie o tíme a alternatívne riešenia, a výskumníci opísali pochopenie kódu a zmien ako kľúčový aspekt kontroly (Bacchelli a Bird, ICSE 2013). Je to štúdia tímov jednej spoločnosti, takže ju použite ako dôvod na návrh pre pochopenie, nie ako sadzbu pre ten váš.
Zverejnený štandard pre recenzie spoločnosti Google poukazuje na to isté. Hovorí recenzentom, aby uprednostnili schválenie zmeny, keď jednoznačne zlepší celkový stav kódu, aj keď nie je dokonalý, a uvádza, že recenzia môže vývojárov naučiť niečo nové, takže komentáre, ktoré niekomu pomôžu učiť sa, sú vítané (Inžinierske postupy spoločnosti Google). Oba zdroje opisujú preskúmanie ako miesto, kde sa uplatňuje a vynáša úsudok. To je to, čo by ste si mali precvičovať vo svojich cvičeniach.
2. Diagnostikovať medzery vo vzdelávaní a kontexte
Porovnajte úlohu s tým, čo váš súčasný program precvičuje a hodnotí.
- Využíva súčasná prax skutočnú úlohu? Ak sa noví recenzenti učia čítaním štýlového sprievodcu a následným prezeraním živých pull requestov, precvičujú si ich na skutočnej práci bez bezpečného miesta, kde by sa mohli mýliť. Ak je hodnotenie kvízom o etikete recenzií, meria zapamätanie si pravidiel, nie schopnosť ich aplikovať na zmenu.
- Aký je kognitívny dopyt? V revidovanej Bloomovej taxonómii sa posudzovanie, či je návrh správny, a zvažovanie jeho kompromisov nachádza na úrovni analýzy a hodnotenia a navrhovanie lepšej štruktúry dosahuje úroveň tvorby. Ak sa vaše cvičenia pýtajú iba na „čo tento kód robí?“, zastavia sa pri pochopení. Náš sprievodca priraďovanie vzdelávacích aktivít k Bloomovej taxonómii ukazuje, ako priradiť aktivitu k úrovni.
- Stojí v ceste niečo iné ako zručnosť? Skontrolujte čas kontroly, nástroje, vlastníctvo a normy tímu. Ak majú recenzenti päť minút na jednu žiadosť o zmeny, žiadne cvičenie neprinesie premyslené vysvetlenie. Ak autori berú každý komentár ako kritiku, recenzenti zmiernia svoje zistenia, až kým nepovedia nič. Nahláste tieto príčiny ľuďom, ktorí ich môžu opraviť.
3. Príprava návrhu, prax a spätná väzba
Každej fáze prideľte samostatnú úlohu.
Príprava. Pred začatím si overte, čo recenzenti potrebujú: kontrolný zoznam tímu na kontrolu, princípy dizajnu, na ktorých sa spolieha, a ako čítať rozdiely vo vašich nástrojoch. Udržujte si vlastné tempo a stručnosť. Kontrola odvolania potvrdzuje iba predpoklady a nie je dôkazom, že niekto môže skontrolovať.
Praxou. Použite pripravené zmeny s malým počtom základných obáv rôzneho druhu: chyba v správnosti, problém s udržiavateľnosťou, ako napríklad zmiešané zodpovednosti v úvodnom príklade, nejasný názov alebo chýbajúci test a nejaký kód, ktorý je v poriadku. Požiadajte recenzenta, aby napísal komentár, ktorý by zanechal, zoradil obavy a uviedol, aké ďalšie informácie by chcel. Praktická lekcia CodeRefinery ukazuje, ako to vyzerá: ľudia otvoria žiadosť o zmenu, ktorá obsahuje malú preklep a väčšiu chybu, a potom ju skontrolujú ako kolegovia (CodeRefinery, Precvičovanie kontroly kódu). Vytvorte si svoj vlastný z vlastnej kódovej základne, aby boli konvencie a kompromisy reálne.
Spätná väzba. Prepojte to s rozhodnutiami, ktoré recenzent urobil. „Všimli ste si problém so zaokrúhľovaním, ale vo vašom komentári ste uviedli „toto vyzerá nesprávne“ bez toho, aby ste uviedli, aký vstup to porušuje“ je užitočnejšie ako „nájdené 2 zo 4“.
Živý vstup alebo asynchrónna kontrola? Živé vstupy sú najhodnotnejšie, keď je problém nejednoznačný a recenzenti sa učia z toho, ako vedúci inžinier hovorí, prečo by ho mali nastoliť, alebo ho nechať tak. Asynchrónne hodnotenie postačuje na porovnanie komentárov s anotovaným expertným hodnotením.
4. Vypracujte realistický príklad
Ilustrácia. Manažér technických oddelení by mal pred použitím overiť prípad a kritériá odpovede.
Púzdro. Zmena pridá výpočet zľavy do pokladničnej služby. Prejde testami. V jednej funkcii sa aplikujú percentuálne a fixné zľavy, zaokrúhli sa výsledok, zapíše sa do databázy a odošle sa udalosť. Má jeden test, pre jednopercentuálnu zľavu.
Úloha. Recenzent zapíše komentáre, ktoré by zanechali, zoradí ich pripomienky a povie, čo by potrebovali vedieť pred schválením.
Prvý pokus. „Vyzerá to dobre, test prešiel. Možno to rozdeliť?“ Recenzent si niečo všimol, ale nepovedal čo, prečo je to dôležité alebo čo má robiť. Autor s tým nemôže konať.
Spätná väzba a pokus znova. Facilitátor sa pýta: aká budúca zmena tejto funkcie by mohla spôsobiť zlyhanie? Čo by ste požiadali autora, aby doplnil pred schválením? Opakovaný pokus vyžaduje konkrétny komentár ku každému problému s uvedením dôvodu a návrhu.
Silnejší pokus. „Funkcia aplikuje dva druhy zliav, zaokrúhľuje, ukladá a publikuje udalosť, takže zmena zaokrúhľovania by mohla zmeniť to, čo ukladáme a čo zároveň publikujeme. Žiadal by som, aby sa pravidlá stanovovania cien presunuli do čistej funkcie, ktorú môžeme testovať samostatne. Jeden test pokrýva iba percentuálnu zľavu. Žiadal by som o pevnú zľavu a objednávku, ktorá vynuluje celkovú sumu. Nie som si istý, či sa má udalosť spustiť, keď je celková suma nula, preto by som sa opýtal autora.“ Všimnite si, že tento komentár pomenúva problém, uvádza dôvod, konkrétny návrh a uvádza, čo recenzent nevie.
5. Posúdenie spôsobilosti a plánovanie prenosu
Dôkazom schopnosti je výkon pri novej zmene, ktorú hodnotiteľ nevidel. Ohodnoťte presnosť zistení a užitočnosť vysvetlenia. Jednoduchá rubrika používa stupnicu od 0 do 2 pre každé kritérium:
| kritérium | Pozorovateľné dôkazy |
|---|---|
| Vykonanie úlohy | Nájde relevantné problémy v zmene a zaznamená dôkazy pre každý z nich. |
| uvažovanie | Vysvetľuje, prečo je každá obava dôležitá, ponúka alternatívu a hovorí o tom, čo zostáva neisté. |
| Hranice | Dodržiava pravidlá tímu pre hodnotenie a žiada o pomoc alebo informácie, keď chýba autorita alebo kontext. |
Kotvy: 0 znamená chýbajúce alebo nepodložené, 1 znamená čiastočné s relevantnými opomenutiami a 2 znamená úplné a odôvodnené podľa dohodnutých kritérií. Kritické chyby definujte samostatne, napríklad schválenie zmeny s rizikom straty údajov, aby dobré celkové skóre nemohlo žiadne riziko zakryť. Kritériá upravte s technickým manažérom; táto rubrika je východiskovým návrhom, nie validovaným štandardom pripravenosti. Viac informácií o zdôvodňovaní bodovania nájdete v našej príručke navrhovanie interaktívnych cvičení s užitočnou spätnou väzbou.
Naplánujte si prenos. Po cvičení si o niekoľko týždňov skontrolujte vzorku skutočných recenzií od hodnotiteľa s použitím rovnakých kritérií. Porovnajte ich s východiskovým stavom zisteným pred školením a vopred definujte populáciu a časový harmonogram. Pred priznaním kreditov za cvičenia si pozrite ďalšie zmeny, ku ktorým došlo v rovnakom období, ako napríklad nový nástroj na kontrolu alebo zmenu personálneho obsadenia.
6. Cvičenie môžete vykonávať naživo alebo vlastným tempom pomocou AhaSlides
Cvičenie môžete spustiť na workshope alebo nechať recenzentov, aby si ho prepracovali sami. V živom vysielaní ukážte pripravenú zmenu a použite interaktívne snímky na diskusiu:
- Vyberte odpoveď pre otázku „ktorú obavu by ste nastolili ako prvú?“ s možnosťami uvedených obáv. Pred zverejnením vlastného poradia ukážte rozpätie.
- Open Ended pre „napíšte komentár, ktorý by ste zanechali“. Recenzenti môžu porovnať svoje znenie s ostatnými, a práve tu sa prejaví ich schopnosť vysvetľovať.
- Stupnica hodnotenia na otázku „aké je to závažné?“, aby skupina mohla vidieť, kde sa úsudky líšia, a prediskutovať prečo.
Pre recenzentov, ktorí sa nemôžu zúčastniť, je možné použiť rovnakú postupnosť vo vlastnom tempe, pričom po každej odpovedi sa zobrazí anotovaná odborná recenzia. Akékoľvek tvrdenie o vykonávaní kódu, integráciách alebo funkciách umelej inteligencie považujte za nepotvrdené, kým si ho nevyskúšate s vlastným materiálom.
Ak školíte aj recenzentov v oblasti kódu písaného umelou inteligenciou, pozrite si nášho sprievodcu na Školenie pre kontrolu kódu generovaného umelou inteligenciouTen príspevok je o audite vygenerovaných výstupov. Tento je o tom, ako si ľudia navzájom kontrolujú prácu a ako vysvetľujú, čo zistia.
Obmedzenia, ktoré môžu pretrvávať
- Čas kontroly. Premyslený komentár trvá dlhšie ako „LGTM“ a termíny sa posúvajú smerom ku kratšej verzii.
- Tímové normy. Ak sa spätná väzba interpretuje ako osobná kritika, recenzenti svoje zistenia zmiernia alebo ich upustia.
- Krytie prípadu. Jedno cvičenie ukazuje niekoľko druhov obáv. Skóre neopisuje úsudok recenzenta vo všeobecnosti.
- Transfer. Výkon v dielni nie je to isté ako výkon v rušnom rade, preto si overte aj skutočné recenzie.
Včas ich pomenujte sponzorom a naplánujte samostatné opravy. Cvičenia zlepšujú to, čo recenzent môže vidieť a vysvetliť. Nevytvárajú čas ani normy.
Často kladené otázky
Čo sú to cvičenia na kontrolu kódu?
Sú to pripravené praktické úlohy, v ktorých vývojár posúdi zmenu so známymi obavami, zapíše komentáre, ktoré by zanechal, a získa spätnú väzbu o presnosti a užitočnosti. Cieľom je rozvíjať zručnosti recenzenta, nie odovzdať zmenu.
Ako hodnotíte, či sa zlepšil úsudok recenzenta?
Uveďte novú zmenu, ktorú nevideli, a ohodnoťte zistenia a vysvetlenie podľa dohodnutých kritérií. Potom o niekoľko týždňov neskôr skontrolujte vzorku skutočných recenzií. Kvíz o pravidlách recenzií potvrdí iba splnenie predpokladov.
Je peer review kódu hlavne o hľadaní chýb?
Hľadanie chýb je stále hlavnou motiváciou, ale jedna štúdia v spoločnosti Microsoft zistila, že recenzie sa menej zameriavali na chyby, ako sa očakávalo, a zároveň priniesli zdieľanie znalostí a povedomie tímu. Navrhujte cvičenia, ktoré odmeňujú vysvetlenie a pochopenie, ako aj počet chýb.
Kde začať
Vyberte si jeden druh zmeny, ktorú váš tím často kontroluje. Napíšte vyhlásenie o výkonnosti, požiadajte vedúceho inžiniera, aby pripravil jednu zmenu s tromi alebo štyrmi základnými problémami a vypracujte trojkritériovú rubriku so stupnicou od 0 do 2 a zoznamom kritických chýb. Pilotujte to s malou skupinou a potom porovnajte ich ďalšie skutočné kontroly s východiskovým stavom.
Ak chcete vidieť, ako by sa dalo cvičenie s kontrolou spustiť naživo s vaším vlastným tímom a následne ho znova použiť vlastným tempom, preskúmajte AhaSlides.
