Kodegennemgangsøvelser: hvordan man bruger peer review til at udvikle analyse og teknisk vurdering

En udvikler åbner en pull request, der tilføjer en rabatberegning til en checkout-tjeneste. Testene består, og diff'en er kort. En korrekturlæser godkender den på to minutter med "LGTM". Tre måneder senere skal en teamkammerat ændre den samme funktion og opdager, at den blander prisregler, afrunding og databaseadgang på ét sted. Ingen kan med sikkerhed sige, hvad den må.

Dette er et illustrativt scenarie, ikke en dokumenteret hændelse. Det viser, hvad peer-code review kan producere, når det fungerer som en læringsaktivitet: en korrekturlæser, der kan se en plausibel ændring, identificere problemet, der endnu ikke er en fejl, og forklare det på en måde, som forfatteren kan handle på.

Denne vejledning er til tekniske supportledere og tekniske ledere. Den viser, hvordan man designer øvelser i kodegennemgang der bygger den færdighed med vilje, i stedet for at håbe på, at anmelderne henter den fra køen. Den dækker præstationsproblemet, hullerne, der skal diagnosticeres, hvordan man strukturerer forberedelse og øvelse, et fungerende eksempel, og hvordan man kontrollerer, at færdigheden overføres til rigtige anmeldelser. Få ledende ingeniører til at validere alle tilfælde, mangler og kriterier, før du bruger den.

Hvad er kodegennemgangsøvelser?

Kodegennemgangsøvelser er strukturerede øvelsesopgaver, hvor en udvikler gennemgår en forberedt ændring, forklarer, hvad de har fundet, og hvorfor det er vigtigt, og får feedback på kvaliteten af ​​denne forklaring. De er forskellige fra de gennemgange, dit team foretager hver dag. Ændringen er valgt på forhånd, bekymringerne i den er kendte, og målet er at forbedre den, der anmelder den, snarere end at aflevere ændringen.

hurtige fakta

1. Beskriv ydeevneproblemet

Start med opgaven, i én sætning: I tilfælde af en ændring forklarer anmelderen, hvad de fandt, hvorfor det er vigtigt, og hvad forfatteren kan gøre ved det. "Forklarer" er det vigtige ord. At identificere et problem er halvdelen af ​​færdigheden. At sige det, så en kollega med et andet synspunkt kan forstå det, vurdere det og handle, er den anden halvdel.

Forskning i moderne kodegennemgang understøtter at se ud over fejlsøgning. I en undersøgelse hos Microsoft observerede, interviewede og adspurgte Bacchelli og Bird udviklere og ledere. De fandt ud af, at det at finde defekter stadig var den primære motivation for gennemgang, men at gennemgange handlede mindre om defekter, end folk forventede. De gav også andre fordele, såsom videndeling, teambevidsthed og alternative løsninger, og forskerne beskrev forståelse af kode og ændringer som det centrale aspekt ved gennemgang (Bacchelli og Bird, ICSE 2013Det er et studie af én virksomheds teams, så brug det som en grund til at designe med forståelse for øje, ikke som en sats for dine egne.

Googles offentliggjorte gennemgangsstandard peger i samme retning. Den fortæller anmeldere, at de skal foretrække at godkende en ændring, når den definitivt forbedrer kodens generelle tilstand, selvom den ikke er perfekt, og den siger, at gennemgang kan lære udviklere noget nyt, så kommentarer, der hjælper nogen med at lære, er velkomne (Googles tekniske praksisBegge kilder beskriver evaluering som et sted, hvor vurdering udøves og fældes. Det er det, dine øvelser bør øve sig på.

2. Diagnosticer lærings- og kontekstmanglerne

Sammenlign opgaven med, hvad dit nuværende program praktiserer og vurderer.

1. Bruger nuværende praksis den virkelige opgave? Hvis nye korrekturlæsere lærer ved at læse en stilguide og derefter gennemgå live pull requests, øver de sig på rigtigt arbejde uden noget sikkert sted at tage fejl. Hvis evaluering er en quiz om korrekturetikette, måler den genkendelse af reglerne, ikke evnen til at anvende dem på en ændring.
2. Hvad er den kognitive efterspørgsel? I den reviderede Blooms taksonomi ligger vurderingen af, om et design er solidt, og afvejningen af ​​dets afvejninger på analyse- og evalueringsniveauet, og forslag til en bedre struktur når skabelsesniveauet. Hvis dine øvelser kun spørger "hvad gør denne kode?", stopper de ved forståelse. Vores guide til Matching af læringsaktiviteter til Blooms taksonomi viser, hvordan man matcher aktiviteten med niveauet.
3. Er der noget andet end færdigheder, der kommer i vejen? Tjek gennemgangstid, værktøjer, ejerskab og teamnormer. Hvis korrekturlæsere har fem minutter pr. pull request, vil ingen øvelse give en gennemtænkt forklaring. Hvis forfattere tager enhver kommentar som kritik, vil korrekturlæserne blødgøre deres resultater, indtil de ikke siger noget. Rapportér disse årsager til de personer, der kan rette dem.

3. Designforberedelse, øvelse og feedback

Giv hvert trin et separat job.

Forberedelse. Tjek, hvad anmelderne har brug for, før de starter: teamets tjekliste for gennemgang, de designprincipper, den er baseret på, og hvordan man aflæser en difference i dine værktøjer. Hold dette i eget tempo og kort. En tilbagekaldelseskontrol bekræfter kun forudsætninger, og det er ikke bevis for, at nogen kan gennemgå.

Øve sig. Brug forberedte ændringer med et lille antal forudsete bekymringer af forskellig art: en korrekthedsfejl, et vedligeholdelsesproblem såsom de blandede ansvarsområder i åbningseksemplet, et uklart navn eller manglende test, og noget kode, der er fin. Bed korrekturlæseren om at skrive den kommentar, de ville efterlade, rangordne bekymringerne og sige, hvilke yderligere oplysninger de ønsker. CodeRefinerys praktiske lektion viser formen: folk åbner en pull request, der indeholder en lille tastefejl og en større fejl, og gennemgår den derefter som en peer (CodeRefinery, Øvelse i kodegennemgang). Byg din ud fra din egen kodebase, så konventionerne og afvejningerne er reelle.

Feedback. Forbind det med de beslutninger, som anmelderen traf. "Du bemærkede afrundingsproblemet, men din kommentar sagde 'dette ser forkert ud' uden at angive, hvilket input der defekter det" er mere nyttigt end "fandt 2 ud af 4".

Live input eller asynkron gennemgang? Live input tilføjer mest værdi, når en bekymring er tvetydig, og anmeldere lærer af at høre en ledende ingeniør sige, hvorfor de ville rejse den, eller lade den ligge. Asynkron gennemgang er tilstrækkelig til at sammenligne kommentarer med en kommenteret ekspertgennemgang.

4. Arbejd dig igennem et realistisk eksempel

Illustrativt. En teknisk leder bør validere casen og svarkriterierne før brug.

Sagen. En ændring tilføjer en rabatberegning til en kassetjeneste. Den består sine tests. I én funktion anvender den procentvise og faste rabatter, afrunder resultatet, skriver til databasen og sender en hændelse. Den har én test for en enkelt procentvis rabat.

Opgaven. Anmelderen skriver de kommentarer, de ville efterlade, rangerer deres bekymringer og siger, hvad de skal vide, før de godkender.

Et første forsøg. "Ser fint ud, testen består. Måske skal den opdeles?" Anmelderen har bemærket noget, men har ikke sagt hvad, hvorfor det er vigtigt, eller hvad man skal gøre. Forfatteren kan ikke reagere på dette.

Feedback og forsøg igen. Facilitatoren spørger: Hvad ville en fremtidig ændring af denne funktion risikere at bryde sammen? Hvad ville du bede forfatteren om at tilføje, før du godkender? Det nye forsøg beder om en specifik kommentar til hvert problem med begrundelsen og et forslag.

Et stærkere forsøg. "Funktionen anvender to slags rabatter: runder, gemmer og publicerer en begivenhed, så en ændring af afrunding kan ændre, hvad vi gemmer, og hvad vi publicerer på samme tid. Jeg vil bede om, at prisreglerne flyttes til en ren funktion, vi kan teste alene. Den enkelte test dækker kun en procentvis rabat. Jeg vil bede om en fast rabat og en ordre, der bringer totalen til nul. Jeg er ikke sikker på, om begivenheden er beregnet til at udløses, når totalen er nul, så jeg vil spørge forfatteren." Bemærk, at denne kommentar nævner bekymringen, giver årsagen, kommer med et konkret forslag og angiver, hvad anmelderen ikke ved.

5. Vurder kapacitet og planoverførsel

Bevis for evne er præstation på en ny ændring, som anmelderen ikke har set. Giv score for nøjagtigheden af ​​resultaterne og forklaringens anvendelighed. En simpel rubrik bruger en skala fra 0 til 2 pr. kriterium:

Ankre: 0 betyder fraværende eller ikke-understøttet, 1 betyder delvis med relevante udeladelser, og 2 betyder fuldstændig og begrundet i forhold til aftalte kriterier. Definer kritiske fejl separat, for eksempel godkendelse af en ændring med en risiko for datatab, så en god samlet score ikke kan skjule en. Tilpas kriterierne med den tekniske leder; denne rubrik er et startforslag, ikke en valideret parathedsstandard. For mere information om begrundelse for scoring, se vores guide til design af interaktiv praksis med nyttig feedback.

Planlæg overførsel. Efter øvelsen skal du kontrollere en stikprøve af anmelderens faktiske anmeldelser et par uger senere med de samme kriterier. Sammenlign med en baseline taget før træningen, og definer populationen og timingen på forhånd. Se på andre ændringer, der er sket i samme periode, såsom et nyt evalueringsværktøj eller en ændring i personale, før du krediterer øvelserne.

6. Kør øvelsen live eller i dit eget tempo med AhaSlides

Du kan udføre øvelsen i en workshop eller lade evaluatorerne arbejde sig igennem den på egen hånd. Vis den forberedte ændring i en live-session og brug interaktive slides til diskussionen:

1. Vælg svar for "hvilken bekymring ville du rejse først?", med de opstillede bekymringer som muligheder. Vis spredningen, før du afslører din egen rangering.
2. Åben afsluttet for "skriv den kommentar, du ville efterlade". Anmeldere kan sammenligne deres formuleringer med andre, hvilket er hvor deres forklaringsevne kommer til udtryk.
3. Vurderingsskala for "hvor alvorligt er dette?", så gruppen kan se, hvor vurderingerne er forskellige, og tale om hvorfor.

For korrekturlæsere, der ikke kan deltage, kan den samme sekvens bruges i eget tempo, med den kommenterede ekspertanmeldelse vist efter hvert svar. Behandl enhver påstand om kodeudførelse, integrationer eller AI-funktioner som ubekræftet, indtil du har prøvet det med dit eget materiale.

Hvis du også træner korrekturlæsere i AI-skrevet kode, kan du se vores tilhørende vejledning om Træning i AI-genereret kodegennemgangDet indlæg handler om at revidere genereret output. Dette handler om, hvordan folk gennemgår hinandens arbejde, og hvordan de forklarer, hvad de finder.

Begrænsninger, der kan forblive

• Gennemgangstid. En tankevækkende kommentar tager længere tid end "LGTM", og deadlines rykker sig mod den korte version.
• Holdnormer. Hvis feedback læses som en personlig kritik, vil anmelderne bløde op eller droppe deres resultater.
• Sagsdækning. Én øvelse viser et par former for bekymring. En score beskriver ikke en anmelders vurdering generelt.
• Overførsel. Optræden i et værksted er ikke det samme som optræden i en travl kø, så tjek også rigtige anmeldelser.

Nævn disse for sponsorerne tidligt og planlæg separate løsninger. Øvelser forbedrer, hvad en anmelder kan se og forklare. De skaber ikke tiden eller normerne.

Ofte stillede spørgsmål

Hvad er kodegennemgangsøvelser?

Det er forberedte øvelsesopgaver, hvor en udvikler gennemgår en ændring med kendte bekymringer, skriver de kommentarer, de ville efterlade, og får feedback på nøjagtighed og anvendelighed. Målet er at opbygge anmelderens færdigheder, ikke at levere ændringen.

Hvordan vurderer du, om en anmelders dømmekraft er blevet forbedret?

Giv en ny ændring, de ikke har set, og bedøm resultaterne og forklaringen i forhold til de aftalte kriterier. Tjek derefter en stikprøve af rigtige anmeldelser nogle uger senere. En quiz om anmeldelsesregler bekræfter kun forudsætningerne.

Handler peer-kodegennemgang primært om at finde fejl?

At finde fejl er stadig en primær motivation, men en undersøgelse hos Microsoft viste, at evalueringer handlede mindre om fejl end forventet og også leverede videndeling og teambevidsthed. Designøvelser, der belønner forklaring og forståelse samt antallet af fejl.

Hvor skal man begynde

Vælg én type ændring, som dit team ofte gennemgår. Skriv præstationserklæringen, bed en ledende ingeniør om at forberede én ændring med tre eller fire udpegede bekymringer, og udarbejd en rubrik med tre kriterier med en skala fra 0 til 2 og en liste over kritiske fejl. Afprøv det med en lille gruppe, og sammenlign derefter deres næste rigtige gennemgange med et baseline.

For at se, hvordan en repetitionsøvelse kan køre live med dit eget team og genbruges i dit eget tempo bagefter, kan du udforske AhaSlides.