Egy fejlesztő megnyit egy pull requestet, amely egy kedvezményszámítást ad hozzá egy fizetési szolgáltatáshoz. A tesztek sikeresek, de a különbség rövid. Egy felülvizsgáló két perc alatt jóváhagyja az "LGTM" jóváhagyásával. Három hónappal később egy csapattársnak módosítania kell ugyanazt a függvényt, és rájön, hogy az egy helyen keveri az árképzési szabályokat, a kerekítést és az adatbázis-hozzáférést. Senki sem tudja magabiztosan megmondani, hogy mit szabad tennie.
Ez egy szemléltető forgatókönyv, nem egy dokumentált incidens. Azt mutatja meg, hogy mit kell produkálnia a peer code review-nak, amikor tanulási tevékenységként működik: egy olyan felülvizsgálót, aki képes észrevenni a valószínűsíthető változást, észrevenni az aggályt, ami még nem hiba, és olyan módon elmagyarázni, hogy a szerző cselekedni tudjon.
Ez az útmutató mérnöki képzési vezetők és mérnöki menedzserek számára készült. Bemutatja, hogyan kell megtervezni kódáttekintési gyakorlatok amelyek szándékosan fejlesztik az adott készséget, ahelyett, hogy reménykednének abban, hogy a felülvizsgálók a sorból választják ki. Kitér a teljesítményproblémára, a diagnosztizálandó hiányosságokra, a felkészülés és a gyakorlás strukturálására, egy gyakorlati példára, és arra, hogyan ellenőrizhető, hogy a készség átvihető-e a valódi felülvizsgálatokra. Használat előtt minden esetet, hibát és kritériumot validáljon a vezető mérnökök.
Mik azok a kódáttekintési gyakorlatok?
A kódátvizsgálási gyakorlatok strukturált gyakorlófeladatok, amelyek során a fejlesztő áttekint egy előkészített módosítást, elmagyarázza, mit talált és miért fontos, majd visszajelzést kap a magyarázat minőségéről. Ezek különböznek a csapat által nap mint nap végzett átvizsgálásoktól. A módosítást előre kiválasztják, a benne rejlő aggályok ismertek, és a cél a felülvizsgáló fejlesztése, nem pedig a módosítás elküldése.
Gyors tények
| Kérdés | Rövid válasz |
|---|---|
| Mi a feladat? | Magyarázd el az értékelés megállapításait, és adj visszajelzést, amely alapján a szerző cselekedhet. |
| Mit érsz el? | A megállapítások pontossága és a magyarázat hasznossága. |
| Elég a hibák számbavétele? | Nem. A vélemények többről szólnak, mint hibákról, így egy olyan gyakorlat, amely csak a hibák számát jutalmazza, rossz szokást képez. |
| Mi a kognitív igény? | Elemezd és értékeld a tervet, majd készíts egy jobb javaslatot. |
| Ki igazolja az esetet? | Egy mérnöki vezető vagy vezető mérnök, aki a kódbázis tulajdonosa. |
| Mit nem oldanak meg a gyakorlatok? | Felülvizsgálati idő, tisztázatlan tulajdonjog és a gyors egyesülésre irányuló nyomás. |
| Honnan tudod, hogy működött? | Egy új, láthatatlan változás, amelyet a megállapodott kritériumok alapján felülvizsgáltak, valamint a valódi felülvizsgálatok nyomon követése. |
1. Írd le a teljesítményproblémát
Kezdjük a feladattal, egyetlen mondatban: adott esetben a bíráló elmagyarázza, mit talált, miért fontos, és mit tehet a szerző ellene. A „magyarázat” a legfontosabb szó. A probléma felismerése a képesség fele. A másik fele az, hogy egy más nézőponttal rendelkező kolléga is megértheti, mérlegelheti és cselekedhet.
A modern kódellenőrzéssel kapcsolatos kutatások alátámasztják, hogy a hibák keresésén túlmutató gondolkodásmódot érdemes figyelembe venni. Egy Microsoftnál végzett tanulmányban Bacchelli és Bird megfigyelték, interjút készítettek és felmérték a fejlesztőket és a vezetőket. Azt találták, hogy a hibák keresése továbbra is a felülvizsgálat fő motivációja, de a felülvizsgálatok kevésbé szóltak a hibákról, mint ahogy az emberek várták. Más előnyökkel is jártak, például a tudásmegosztással, a csapat tudatosságával és az alternatív megoldásokkal, a kutatók pedig a kód és a változások megértését írták le a felülvizsgálat kulcsfontosságú aspektusaként (Bacchelli és Bird, ICSE 2013). Ez egy vállalat csapatainak tanulmányozása, ezért a megértést célzó tervezés indokaként használd, ne pedig a sajátodra vonatkozó árképzésként.
A Google közzétett felülvizsgálati szabványa ugyanerre a következtetésre jut. Azt mondja a felülvizsgálóknak, hogy részesítsék előnyben egy változtatás jóváhagyását, ha az határozottan javítja a kód általános állapotát, még akkor is, ha az nem tökéletes, és azt állítja, hogy a felülvizsgálat valami újat taníthat a fejlesztőknek, ezért szívesen látjuk azokat a megjegyzéseket, amelyek segítenek valakinek tanulni (Google Mérnöki Gyakorlatok). Mindkét forrás a felülvizsgálatot olyan helyként írja le, ahol az ítélkezés megnyilvánul és továbbadódik. Ezt kell gyakorolnod a gyakorlataid során.
2. A tanulási és kontextuális hiányosságok diagnosztizálása
Hasonlítsd össze a feladatot azzal, amit a jelenlegi programod gyakorol és értékel.
- A jelenlegi gyakorlat a valódi feladatot használja? Ha az új bírálók egy stíluskalauz elolvasásával, majd élő pull requestek áttekintésével tanulnak, akkor valódi munkán gyakorolnak, ahol nincs biztonságos hely a hibázásra. Ha az értékelés a bírálati etikett kvíze, akkor a szabályok felidézését méri, nem pedig a változtatásokra való alkalmazásuk képességét.
- Mi a kognitív igény? A felülvizsgált Bloom-taxonómiában egy terv megalapozottságának megítélése és a kompromisszumok mérlegelése az elemzés és értékelés szintjén történik, míg egy jobb struktúra javaslata a létrehozás szintjén. Ha a gyakorlatok csak azt kérdezik, hogy „mit csinál ez a kód?”, akkor megállnak a megértésnél. Útmutatónk a következőhöz: tanulási tevékenységek Bloom taxonómiájához való illesztése megmutatja, hogyan kell a tevékenységet a szinthez igazítani.
- Vajon a képességen kívül valami más is akadályozza? Ellenőrizd az értékeléshez szükséges időt, az eszközöket, a felelősségvállalást és a csapat normáit. Ha a felülvizsgálóknak öt percük van kérésenként, egyetlen feladat sem fog átgondolt magyarázatot eredményezni. Ha a szerzők minden megjegyzést kritikaként vesznek fel, a felülvizsgálók addig finomítják a megállapításaikat, amíg egy szót sem szólnak. Jelentsd ezeket az okokat azoknak, akik kijavíthatják azokat.
3. Tervezés előkészítése, gyakorlás és visszajelzés
Minden szakasznak adj külön feladatot.
Készítmény. Mielőtt elkezdenék, ellenőrizd, mire van szükségük a felülvizsgálóknak: a csapat felülvizsgálati ellenőrzőlistáját, a tervezési alapelveket, amelyekre támaszkodik, és azt, hogyan kell értelmezni a szerszámokban lévő különbségeket. Tartsd ezt az ellenőrzést saját tempóban és röviden. A visszahívási ellenőrzés csak az előfeltételeket erősíti meg, és nem bizonyítja, hogy valaki képes felülvizsgálni.
Gyakorlat. Használjon előkészített módosításokat néhány, különböző típusú, előzetesen meghatározott aggodalommal: helyességi hiba, karbantarthatósági probléma, például a nyitó példában szereplő vegyes felelősségek, nem egyértelmű név vagy hiányzó teszt, és néhány megfelelő kód. Kérje meg a felülvizsgálót, hogy írja meg a hozzáfűzni kívánt megjegyzést, rangsorolja az aggályokat, és mondja el, milyen további információkat szeretne. A CodeRefinery gyakorlati leckéje bemutatja a formát: az emberek megnyitnak egy pull requestet, amely egy kis elgépelést és egy nagyobb hibát tartalmaz, majd egy másik felhasználóként áttekintik (CodeRefinery, Kódátvizsgálás gyakorlása). Építsd fel a sajátodat a saját kódbázisodból, hogy a konvenciók és kompromisszumok valósak legyenek.
Visszacsatolás. Kapcsold össze a véleményező döntéseivel. Az „Észrevetted a kerekítési problémát, de a hozzászólásodban azt írtad, hogy „ez rosszul néz ki”, anélkül, hogy megmondtad volna, melyik bemenet hibás” válasz hasznosabb, mint a „4-ből 2 találat”.
Élő bemenet vagy aszinkron értékelés? Az élő visszajelzés akkor ad a legtöbb értéket, ha egy aggály kétértelmű, és a véleményezők abból tanulnak, hogy egy vezető mérnök elmondja, miért vetik fel, vagy miért nem. Az aszinkron értékelés elegendő ahhoz, hogy az észrevételeket összehasonlítsuk egy jegyzetekkel ellátott szakértői értékeléssel.
4. Dolgozz ki egy valós példát
Szemléltető példa. A mérnöki vezetőnek használat előtt validálnia kell az esetet és a válaszkritériumokat.
Az eset. Egy módosítás kedvezményszámítást ad hozzá egy pénztár szolgáltatáshoz. A függvény átmegy a teszteken. Egyetlen függvényben százalékos és fix kedvezményeket alkalmaz, kerekíti az eredményt, beírja az adatbázisba és eseményt küld. Egyetlen tesztje van, egyetlen százalékos kedvezményhez.
A feladat. A véleményező leírja a véleményezők által hagyott megjegyzéseket, rangsorolja az aggályokat, és elmondja, mit kell tudniuk a jóváhagyás előtt.
Első próbálkozás. „Jól néz ki, a teszt sikerült. Talán bontsuk fel?” A bíráló észrevett valamit, de nem mondta meg, hogy mit, miért fontos, vagy mit tegyen. A szerző nem tud cselekedni.
Visszajelzés és újrapróbálás. A facilitátor megkérdezi: milyen kockázattal járna a függvény jövőbeli módosítása? Mit kérnél a szerzőtől, hogy egészítse ki a jóváhagyás előtt? Az újrapróbálkozás során minden egyes aggályra konkrét megjegyzést kérnek, indoklással és javaslattal együtt.
Egy erősebb próbálkozás. „A függvény kétféle kedvezményt alkalmaz: kerekít, ment és közzétesz egy eseményt, így a kerekítés megváltoztatása befolyásolhatja, hogy mit tárolunk és mit teszünk közzé egyszerre. Azt kérném, hogy az árképzési szabályokat egy tiszta függvénybe helyezzék át, amelyet önállóan tesztelhetünk. Az egyetlen teszt csak a százalékos kedvezményt vizsgálja. Fix kedvezményt és egy olyan sorrendet kérnék, amely nullára hozza az összeget. Nem vagyok biztos benne, hogy az eseménynek akkor kell-e aktiválódnia, amikor az összeg nulla, ezért megkérdezném a szerzőt.” Figyeljük meg, hogy ez a megjegyzés megnevezi az aggályt, megadja az okát, konkrét javaslatot tesz, és leírja, hogy mit nem tud a véleményező.
5. Képességfelmérés és a terv átadása
A képesség bizonyítéka egy olyan új változtatáson elért teljesítmény, amelyet a bíráló még nem látott. Értékelje a megállapítások pontosságát és a magyarázat hasznosságát. Egy egyszerű értékelőlap kritériumonként 0-tól 2-ig terjedő skálát használ:
| Kritérium | Megfigyelhető bizonyítékok |
|---|---|
| Feladat végrehajtása | Megkeresi a változásban rejlő aggályokat, és mindegyikre vonatkozóan rögzíti a bizonyítékokat. |
| Érvelés | Elmagyarázza, hogy miért fontos az egyes aggályok, alternatívát kínál, és kimondja, mi marad bizonytalan. |
| Határok | Követi a csapat értékelési szabályait, és segítséget vagy információt kér, ha hiányzik a tekintély vagy a kontextus. |
Horgonypontok: 0 hiányzót vagy nem támogatottat jelent, 1 részlegeset, releváns hiányosságokkal, és 2 teljest és a megállapodás szerinti kritériumok alapján indokoltat jelent. A kritikus hibákat külön kell meghatározni, például egy adatvesztési kockázattal járó változtatás jóváhagyásakor, hogy a jó összpontszám ne rejthessen el egy kockázatot. A kritériumokat a műszaki vezetővel együtt kell módosítani; ez a rubrika egy kiindulási javaslat, nem pedig egy validált készültségi szabvány. A pontozási indoklással kapcsolatos további információkért lásd az útmutatónkat. interaktív gyakorlatok tervezése hasznos visszajelzésekkel.
Áthelyezés megtervezése. A gyakorlat után, néhány héttel később, ugyanazon kritériumok alapján ellenőrizze a felülvizsgáló valódi értékeléseinek mintáját. Hasonlítsa össze az eredményeket a képzés előtt felvett alapértékekkel, és előre határozza meg a populációt és az időzítést. A gyakorlatok jóváírása előtt vizsgálja meg az ugyanebben az időszakban történt egyéb változásokat, például egy új felülvizsgálati eszközt vagy a személyzet változását.
6. Végezd el a gyakorlatot élőben vagy saját tempóban a AhaSlides
A gyakorlatot elvégezheted egy workshopon, vagy hagyhatod, hogy a véleményezők önállóan is elvégezzék. Egy élő előadás során mutasd be az előkészített módosítást, és használj interaktív diákat a megbeszéléshez:
- Válasszon választ a „melyik aggályt vetnéd fel először?” kérdésre, a kiemelt aggályokkal választható lehetőségekként. Mutasd meg a szórást, mielőtt felfeded a saját rangsorodat.
- Nyíltvégű „írd meg a hozzáfűznivalódat”. A véleményezők összehasonlíthatják a saját megfogalmazásukat másokéval, ami megmutatkozik a magyarázó készségben.
- Értékelési skála a „mennyire súlyos ez?” kérdésre, hogy a csoport lássa, miben térnek el az ítéletek, és megbeszélhessék, miért.
Azok a bírálók, akik nem tudnak részt venni, ugyanazt a sorrendet használhatják saját tempójukban, a válaszok után megjelenő, jegyzetekkel ellátott szakértői értékeléssel. A kódfuttatásra, integrációkra vagy mesterséges intelligencia funkciókra vonatkozó állításokat mindaddig nem megerősítettnek tekintsék, amíg ki nem próbálták a saját anyagukkal.
Ha mesterséges intelligencia által írt kódra is képzed a bírálókat, tekintsd meg a kapcsolódó útmutatónkat a következő címen: Mesterséges intelligencia által generált kód áttekintési képzésEz a bejegyzés a generált kimenet auditálásáról szól. Ez pedig arról, hogyan értékelik az emberek egymás munkáját, és hogyan magyarázzák el a megállapításaikat.
Maradhatnak korlátok
- Felülvizsgálati idő. Egy átgondolt hozzászólás tovább tart, mint az „LGTM”, és a határidők a rövidebb változat felé tolódnak el.
- Csapatnormák. Ha a visszajelzést személyes kritikaként értelmezik, a bírálók enyhítik vagy elhagyják a megállapításaikat.
- Eseti lefedettség. Az egyik gyakorlat néhány aggodalomra ad okot. A pontszám nem általánosságban írja le a bíráló ítéletét.
- Átadása. Egy workshopon nyújtott teljesítmény nem ugyanaz, mint egy zsúfolt sorban állás, ezért érdemes valódi véleményeket is ellenőrizni.
Nevezd meg ezeket a szponzoroknak időben, és tervezz külön javításokat. A gyakorlatok javítják azt, amit a bíráló lát és magyaráz. Nem teremtik meg az időt vagy a normákat.
Gyakran Ismételt Kérdések
Mik azok a kódáttekintési gyakorlatok?
Ezek előre elkészített gyakorló feladatok, amelyek során a fejlesztő áttekint egy ismert aggályokkal bíró változtatást, megírja a hozzá fűzött megjegyzéseket, és visszajelzést kap a pontosságról és a hasznosságról. A cél a felülvizsgáló készségeinek fejlesztése, nem pedig a változtatás végrehajtása.
Hogyan értékeli, hogy egy bíráló ítélőképessége javult-e?
Adj egy új, még nem látott változtatást, és pontozd a megállapításokat és a magyarázatot a megállapodott kritériumok alapján. Ezután néhány héttel később ellenőrizd a valódi értékelések mintáját. Az értékelési szabályokról szóló kvíz csak az előfeltételeket erősíti meg.
A peer code review elsősorban a hibák felkutatásáról szól?
A hibák felkutatása továbbra is fő motiváció, de egy Microsoft-tanulmány szerint az értékelések a vártnál kevésbé foglalkoztak a hibákkal, és tudásmegosztást és csapattudatot eredményeztek. Tervezzen olyan gyakorlatokat, amelyek a magyarázatot és a megértést, valamint a hibák számát jutalmazzák.
Hol kezdjem
Válassz ki egy olyan változtatástípust, amelyet a csapatod gyakran felülvizsgál. Írd meg a teljesítményjelentést, kérj meg egy vezető mérnököt, hogy készítsen elő egy változtatást három vagy négy kiemelt problémával, és készíts egy háromkritériumú értékelőlapot 0-tól 2-ig terjedő skálával és a kritikus hibák listájával. Próbáld ki egy kis csoporttal, majd hasonlítsd össze a következő valós felülvizsgálatokat egy alapértékkel.
Ha szeretnéd megtudni, hogyan futtathatsz le egy értékelési gyakorlatot élőben a saját csapatoddal, és hogyan használhatod fel később önálló tempóban, nézd meg AhaSlides.
