Kūrėjas atidaro užklausą „pull request“, kuria prie atsiskaitymo paslaugos pridedamas nuolaidos skaičiavimas. Testai sėkmingi, o skirtumas nedidelis. Recenzentas patvirtina užklausą per dvi minutes su „LGTM“. Po trijų mėnesių komandos narys turi pakeisti tą pačią funkciją ir aptinka, kad joje vienoje vietoje sumaišytos kainodaros taisyklės, apvalinimas ir prieiga prie duomenų bazės. Niekas negali užtikrintai pasakyti, ką leidžiama daryti.
Tai iliustracinis scenarijus, o ne dokumentuotas incidentas. Jis parodo, ką turi duoti kolegialus kodo peržiūrėjimas, kai jis veikia kaip mokymosi veikla: recenzentas, galintis pamatyti tikėtiną pakeitimą, pastebėti problemą, kuri dar nėra klaida, ir paaiškinti ją taip, kad autorius galėtų imtis veiksmų.
Šis vadovas skirtas inžinerijos įgūdžių lavinimo vadovams ir inžinerijos vadovams. Jame parodyta, kaip projektuoti kodo peržiūros pratimai kurie sąmoningai ugdo tą įgūdį, o ne tikisi, kad recenzentai jį paims iš eilės. Jame aptariama našumo problema, diagnozuojamos spragos, kaip struktūrizuoti pasiruošimą ir praktiką, pateikiamas vienas praktinis pavyzdys ir kaip patikrinti, ar įgūdis taikomas realiose recenzijose. Prieš naudodami, paprašykite vyresniųjų inžinierių patvirtinti kiekvieną atvejį, defektą ir kriterijų.
Kas yra kodo peržiūros pratimai?
Kodo peržiūros pratimai yra struktūrizuotos praktinės užduotys, kurių metu kūrėjas peržiūri parengtą pakeitimą, paaiškina, ką rado ir kodėl tai svarbu, ir gauna atsiliepimus apie to paaiškinimo kokybę. Jos skiriasi nuo peržiūrų, kurias jūsų komanda atlieka kiekvieną dieną. Pakeitimas parenkamas iš anksto, žinomos su juo susijusios problemos, o tikslas – patobulinti peržiūrintįjį, o ne pateikti pakeitimą.
Greiti faktai
| klausimas | Trumpas atsakymas |
|---|---|
| Kokia užduotis? | Paaiškinkite apžvalgos išvadas ir pateikite atsiliepimus, į kuriuos autorius galėtų atsižvelgti. |
| Ką skaičiuoji? | Išvadų tikslumas ir paaiškinimo naudingumas. |
| Ar pakanka skaičiuoti defektus? | Ne. Atsiliepimai yra daugiau nei vien trūkumai, todėl pratimas, kuris vertina tik klaidų skaičių, ugdo neteisingą įprotį. |
| Koks yra kognityvinis poreikis? | Išanalizuokite ir įvertinkite dizainą, o tada sukurkite geresnį pasiūlymą. |
| Kas patvirtina bylą? | Inžinerijos vadovas arba vyresnysis inžinierius, kuriam priklauso kodo bazė. |
| Ko pratimai negali išspręsti? | Peržiūros laikas, neaiškūs savininkai ir spaudimas greitai susijungti. |
| Iš kur žinai, kad suveikė? | Naujas, nematomas pakeitimas, peržiūrėtas pagal sutartus kriterijus, ir tolesni veiksmai po realių peržiūrų. |
1. Aprašykite našumo problemą
Pradėkite nuo užduoties vienu sakiniu: gavus pakeitimą, recenzentas paaiškina, ką rado, kodėl tai svarbu ir ką autorius galėtų dėl to padaryti. Svarbiausias žodis – „paaiškinti“. Problemos pastebėjimas yra pusė įgūdžio. Kita pusė – pasakyti ją taip, kad kolega, turintis kitokią nuomonę, galėtų ją suprasti, apsvarstyti ir imtis veiksmų.
Šiuolaikinės kodo peržiūros tyrimai padeda žvelgti ne tik į klaidų paiešką. „Microsoft“ atliktame tyrime Bacchelli ir Bird stebėjo, kalbino ir apklausė kūrėjus bei vadovus. Jie nustatė, kad defektų paieška vis dar buvo pagrindinė peržiūros motyvacija, tačiau peržiūros buvo mažiau susijusios su defektais, nei žmonės tikėjosi. Jos taip pat davė kitos naudos, pavyzdžiui, dalijimąsi žiniomis, komandos informuotumą ir alternatyvius sprendimus, o tyrėjai kodo ir pakeitimų supratimą apibūdino kaip pagrindinį peržiūros aspektą (Bacchelli ir Bird, ICSE 2013). Tai vienos įmonės komandų tyrimas, todėl naudokite jį kaip priežastį kurti supratimą, o ne kaip savo įkainį.
„Google“ paskelbtas peržiūros standartas nurodo tą patį. Jame nurodoma, kad recenzentai turėtų patvirtinti pakeitimą, kai jis neabejotinai pagerina bendrą kodo būklę, net jei jis nėra tobulas, ir teigiama, kad peržiūra gali išmokyti kūrėjus ko nors naujo, todėl laukiami komentarai, kurie padeda kam nors mokytis („Google“ inžinerijos praktika). Abu šaltiniai apžvalgą apibūdina kaip vietą, kurioje priimamas ir perduodamas sprendimas. Būtent tai ir turėtumėte kartoti atlikdami pratimus.
2. Nustatykite mokymosi ir konteksto spragas
Palyginkite užduotį su tuo, ką praktikuoja ir vertina jūsų dabartinė programa.
- Ar dabartinė praktika naudoja tikrąją užduotį? Jei nauji recenzentai mokosi skaitydami stiliaus vadovą ir peržiūrėdami realius užklausimus, jie praktikuojasi realiame darbe, kur nėra saugios vietos suklysti. Jei vertinimas yra recenzijos etiketo testas, jis matuoja taisyklių prisiminimą, o ne gebėjimą jas pritaikyti pakeitimui.
- Koks yra kognityvinis poreikis? Peržiūrėtoje Bloomo taksonomijoje projekto patikimumo vertinimas ir kompromisų įvertinimas atliekamas analizės ir vertinimo lygmenyse, o geresnės struktūros siūlymas – kūrimo lygmenyje. Jei jūsų pratimai klausia tik „ką šis kodas daro?“, jie apsiriboja supratimu. Mūsų vadovas mokymosi veiklų derinimas su Bloomo taksonomija parodo, kaip pritaikyti veiklą prie lygio.
- Ar kliūčių kelia kažkas kita, o ne įgūdžiai? Patikrinkite peržiūros laiką, įrankius, atsakomybę ir komandos normas. Jei recenzentai kiekvienai užklausai turi penkias minutes, joks pratimas nepateiks apgalvoto paaiškinimo. Jei autoriai kiekvieną komentarą priims kaip kritiką, recenzentai sušvelnins savo išvadas, kol nieko nepasakys. Praneškite apie šias priežastis žmonėms, kurie gali jas išspręsti.
3. Dizaino rengimas, praktika ir atsiliepimai
Kiekvienam etapui skirkite atskirą užduotį.
Paruošimas. Prieš pradėdami, patikrinkite, ko reikia recenzentams: komandos peržiūros kontrolinį sąrašą, projektavimo principus, kuriais ji remiasi, ir kaip suprasti jūsų įrankių skirtumus. Atlikite tai savarankiškai ir trumpai. Atkūrimo patikrinimas patvirtina tik būtinąsias sąlygas ir neįrodo, kad kas nors gali peržiūrėti.
Praktika. Naudokite paruoštus pakeitimus su nedideliu skaičiumi įvairių rūšių iškeltų problemų: teisingumo klaida, priežiūros problema, pvz., mišrios atsakomybės pradiniame pavyzdyje, neaiškus pavadinimas arba trūkstamas testas, ir šiek tiek tinkamo kodo. Paprašykite recenzento parašyti komentarą, kurį jis paliktų, surūšiuoti problemas ir nurodyti, kokios papildomos informacijos jis norėtų. „CodeRefinery“ praktinė pamoka rodo formą: žmonės atidaro užklausą su maža spausdinimo klaida ir didesne klaida, tada peržiūri ją kaip kolega („CodeRefinery“, Kodo peržiūros praktika). Sukurkite savąjį iš savo kodo bazės, kad konvencijos ir kompromisai būtų realūs.
Atsiliepimai. Susiekite tai su recenzento priimtais sprendimais. „Pastebėjote apvalinimo problemą, bet jūsų komentare buvo parašyta „tai atrodo neteisingai“, nenurodant, kokia įvestis ją sugadina“ yra naudingiau nei „rasta 2 iš 4“.
Tiesioginė įvestis ar asinchroninė peržiūra? Tiesioginė konsultacija yra vertingiausia, kai problema yra dviprasmiška, o recenzentai mokosi išgirdę vyresnįjį inžinierių, sakantį, kodėl jie ją iškeltų arba atsisakytų. Asinchroninės peržiūros pakanka norint palyginti komentarus su anotuota eksperto apžvalga.
4. Pateikite realų pavyzdį
Iliustracinis pavyzdys. Prieš naudodamas atvejį ir atsakymo kriterijus, inžinerijos vadovas turėtų juos patvirtinti.
Byla. Pakeitimas prideda nuolaidos skaičiavimą prie atsiskaitymo paslaugos. Jis sėkmingai išlaiko testus. Vienoje funkcijoje pritaikomos procentinės ir fiksuotos nuolaidos, suapvalinamas rezultatas, įrašoma į duomenų bazę ir siunčiamas įvykis. Jis turi vieną testą, skirtą vienai procentinei nuolaidai.
Užduotis. Recenzentas užrašo komentarus, kuriuos jie paliktų, įvertina jų problemas ir nurodo, ką jie turėtų žinoti prieš patvirtindami.
Pirmas bandymas. „Atrodo gerai, testas išlaikytas. Gal padalyti?“ Recenzentas kažką pastebėjo, bet nepasakė, ką, kodėl tai svarbu ar ką daryti. Autorius negali imtis veiksmų.
Atsiliepimas ir bandymas dar kartą. Moderatorius klausia: koks šios funkcijos pakeitimas ateityje galėtų sukelti gedimą? Ką paprašytumėte autoriaus pridėti prieš patvirtinant? Pakartotinio bandymo metu prašoma pateikti konkretų komentarą apie kiekvieną problemą, nurodant priežastį ir pasiūlymą.
Stipresnis bandymas. „Funkcija taiko dviejų rūšių nuolaidas: apvalina, išsaugo ir publikuoja įvykį, todėl apvalinimo pakeitimas gali pakeisti tai, ką saugome ir ką publikuojame tuo pačiu metu. Prašyčiau, kad kainodaros taisyklės būtų perkeltos į gryną funkciją, kurią galėtume išbandyti atskirai. Vienas testas apima tik procentinę nuolaidą. Prašyčiau fiksuotos nuolaidos ir užsakymo, kuris sumažintų bendrą sumą iki nulio. Nesu tikras, ar įvykis turėtų suveikti, kai bendra suma yra nulis, todėl paklausčiau autoriaus.“ Atkreipkite dėmesį, kad šiame komentare įvardijamas rūpestis, pateikiama priežastis, pateikiamas konkretus pasiūlymas ir nurodoma, ko recenzentas nežino.
5. Įvertinkite pajėgumus ir planuokite perdavimą
Gebėjimo įrodymas yra naujo pakeitimo, kurio recenzentas nematė, atlikimas. Įvertinkite išvadų tikslumą ir paaiškinimo naudingumą. Paprastoje vertinimo skalėje kiekvienam kriterijui naudojama 0–2 balų skalė:
| kriterijus | Stebimi įrodymai |
|---|---|
| Užduoties vykdymas | Randa su pakeitimu susijusius rūpesčius ir užfiksuoja kiekvieno iš jų įrodymus. |
| Priežastys | Paaiškina, kodėl kiekvienas rūpestis yra svarbus, siūlo alternatyvą ir nurodo, kas lieka neaišku. |
| Ribos | Laikosi komandos peržiūros taisyklių ir prašo pagalbos ar informacijos, kai trūksta autoriteto ar konteksto. |
Pagrindiniai elementai: 0 reiškia, kad nėra arba neparemta, 1 reiškia dalinį su atitinkamais praleidimais, o 2 reiškia, kad išsamus ir pagrįstas pagal sutartus kriterijus. Kritines klaidas apibrėžkite atskirai, pavyzdžiui, patvirtinus pakeitimą, kylantį duomenų praradimo rizika, kad geras bendras balas jos nepaslėptų. Pritaikykite kriterijus su inžinerijos vadovu; ši vertinimo skalė yra pradinis pasiūlymas, o ne patvirtintas pasirengimo standartas. Daugiau informacijos apie vertinimo pagrindimą rasite mūsų vadove. interaktyvios praktikos kūrimas su naudingu grįžtamuoju ryšiu.
Planuokite perkėlimą. Po pratimo, po kelių savaičių, naudodami tuos pačius kriterijus, patikrinkite recenzento realių apžvalgų imtį. Palyginkite su prieš mokymus surinkta bazine verte ir iš anksto apibrėžkite populiaciją bei laiką. Prieš priskirdami pratimams kreditus, atkreipkite dėmesį į kitus tuo pačiu laikotarpiu įvykusius pokyčius, pvz., naują peržiūros įrankį ar personalo pasikeitimą.
6. Atlikite pratimą tiesiogiai arba savarankiškai naudodami „AhaSlides“
Užduotis galite atlikti seminare arba leisti recenzentams patiems jas atlikti. Tiesioginės sesijos metu parodykite parengtą pakeitimą ir diskusijai naudokite interaktyvias skaidres:
- Pasirinkite atsakymą klausimas „kurį rūpestį pirmiausia iškeltumėte?“, nurodant pirminius rūpesčius kaip atsakymo variantus. Prieš atskleisdami savo reitingą, parodykite skirtumą.
- „Open Ended“ „parašykite komentarą, kurį paliktumėte“. Recenzentai gali palyginti savo formuluotes su kitų, o tai ir parodo aiškinimo įgūdžius.
- Vertinimo skalė „kokia tai sunki situacija?“, kad grupė galėtų pamatyti, kur skiriasi vertinimai, ir aptarti priežastis.
Recenzentams, kurie negali dalyvauti, ta pati seka gali būti naudojama savarankiškam tempui, po kiekvieno atsakymo rodant anotuotą eksperto atsiliepimą. Bet kokius teiginius apie kodo vykdymą, integracijas ar dirbtinio intelekto funkcijas laikykite nepatvirtintais, kol neišbandysite jų su savo medžiaga.
Jei taip pat apmokote recenzentus dirbtinio intelekto rašyto kodo srityje, žr. mūsų papildomą vadovą, skirtą Dirbtinio intelekto sugeneruoto kodo peržiūros mokymaiTas įrašas yra apie sugeneruotos išvesties auditą. Šis – apie tai, kaip žmonės peržiūri vieni kitų darbą ir kaip paaiškina savo išvadas.
Apribojimai, kurie gali likti
- Peržiūros laikas. Apgalvotas komentaras užtrunka ilgiau nei „LGTM“, o terminai stumia link trumpesnės versijos.
- Komandos normos. Jei atsiliepimai interpretuojami kaip asmeninė kritika, recenzentai sušvelnins arba atsisakys savo išvadų.
- Bylos aprėptis. Vienas pratimas rodo keletą susirūpinimo rūšių. Įvertinimas neapibūdina recenzento sprendimo apskritai.
- Perdavimo. Pasirodymas dirbtuvėse nėra tas pats, kas pasirodymas užimtoje eilėje, todėl patikrinkite ir tikrus atsiliepimus.
Iš anksto įvardykite šiuos dalykus rėmėjams ir suplanuokite atskirus taisymus. Pratimai pagerina tai, ką recenzentas gali matyti ir paaiškinti. Jie nesukuria laiko ar normų.
Dažnai užduodami klausimai
Kas yra kodo peržiūros pratimai?
Tai yra iš anksto parengtos praktikos užduotys, kurių metu kūrėjas peržiūri pakeitimą, turintį žinomų problemų, parašo savo paliktus komentarus ir gauna atsiliepimus apie tikslumą ir naudingumą. Tikslas – lavinti recenzento įgūdžius, o ne pateikti pakeitimą.
Kaip vertinate, ar recenzento sprendimas pagerėjo?
Pateikite naują pakeitimą, kurio jie dar nematė, ir įvertinkite išvadas bei paaiškinimą pagal sutartus kriterijus. Po kelių savaičių patikrinkite realių atsiliepimų imtį. Peržiūros taisyklių testas patvirtina tik išankstinius reikalavimus.
Ar kolegų kodo peržiūra daugiausia skirta klaidų paieškai?
Defektų paieška vis dar yra pagrindinė motyvacija, tačiau vienas „Microsoft“ tyrimas parodė, kad apžvalgos buvo mažiau susijusios su defektais nei tikėtasi, be to, jos skatino žinių dalijimąsi ir komandos sąmoningumą. Sukurkite pratimus, kurie įvertintų paaiškinimą ir supratimą, taip pat defektų skaičių.
Kur pradėti
Pasirinkite vieno tipo pakeitimą, kurį jūsų komanda dažnai peržiūri. Parašykite veiklos ataskaitą, paprašykite vyresniojo inžinieriaus parengti vieną pakeitimą su trimis ar keturiais pagrindiniais rūpesčiais ir sudarykite trijų kriterijų vertinimo skalę nuo 0 iki 2 ir kritinių klaidų sąrašą. Išbandykite tai su maža grupe, tada palyginkite jų kitas realias peržiūras su pradine situacija.
Norėdami sužinoti, kaip peržiūros pratimas galėtų būti vykdomas tiesiogiai su jūsų komanda ir vėliau pakartotinai naudojamas savarankiškai, peržiūrėkite „AhaSlides“.
