Bedste praksis for kodegennemgang

Forfatteren fordele ved at få et andet perspektiv på deres opgave og Kode. De vil ofte lære nye tricks eller opdage en potentielt mere optimal måde at løse et bestemt problem på. De vil også implementere deres ændringssæt med selvtillid, fordi de ved, at andre mennesker har tjekket koden for korrekthed og er enige om, at alt er i orden.

Anmelderen nyder godt af at se forskellige tilgange til problemløsning i aktion. De vil også blive bedre til at læse koder, hvilket er meget vigtigt, når man f.eks. dykker ned i et bibliotek, der evalueres til brug i en projekt. Kodegennemgang er også en læringsmulighed for anmelderen i lige så høj grad som for forfatteren: de kan også lære nye tricks.

Den hold som helhed, da gennemgangen af en løsning på et bestemt problem kræver, at man forstår problemet i det mindste på et højt abstraktionsniveau. Det hjælper med at nedbryde eventuelle utilsigtede videnssiloer, der kan opstå i et team. Det vil også øge "busfaktoren": Fordi mindst to personer (helst flere) er opmærksomme på en given ændring, er der mindre sandsynlighed for en situation, hvor ingen i teamet ved, hvordan man opdaterer et modul, eller hvorfor en bestemt fejl opstår.

Kunden drager fordel af hurtigt og sikkert implementerede ændringer og løsninger. Sammen med andre best practices (som f.eks. god testdækning, CI/CD, staging-miljøer osv.) sikrer kodegennemgang også, at det, der implementeres, er sikkert, fornuftigt og opfylder kravene som specificeret.

Hensigten med og brugen af disse retningslinjer

Husk, at disse forslag først og fremmest har til formål at skabe et miljø, der fremmer ambitiøs og effektiv problemløsning, samtidig med at de skaber et sikkerhedsnet og fremmer tillid og gennemsigtighed hos alle teammedlemmer.

Selv om det på det kraftigste anbefales, at et team følger disse retningslinjer, er de ikke tænkt som hårde og faste regler. Denne ramme er heller ikke tænkt som en "proces", der skal følges til punkt og prikke, da stive processer har en tendens til at sænke hastigheden og fremme spild.

Du er mere end velkommen til at bygge videre på disse retningslinjer i dit team. Husk dog, at når udviklere skifter mellem teams, vil de forvente, at kodegennemgang i ethvert team, de kommer til, stadig er baseret på dette dokument. Sørg for, at alle yderligere regler bliver dokumenteret, og bidrag til dette dokument med forbedringer, der har fungeret exceptionelt godt.

Ansvarsområder omkring kodegennemgang

Alle i teamet har et vist ansvar i forbindelse med kodegennemgang. Nedenfor beskrives visse dos and don'ts for kodegennemgang efter rolle i processen.

Projektleder

• DO Sørg for, at dine repositories er velkonfigurerede (f.eks. er det ikke tilladt at flette til din produktionsorienterede gren uden mindst én godkendende gennemgang).
• DO Sørg for, at dit team forstår og anvender denne praksis, og arbejd aktivt for at fremme forståelsen af, hvorfor vi gør tingene på en bestemt måde.
• DO Hold øje med uafgjorte situationer, hvor modstridende meninger ikke kan løses: Som teknisk leder for dit team er det dit ansvar at vælge den mest relevante løsning i sådanne tilfælde og holde arbejdet i gang.
• Men.., IKKE bruge projektledelse som et stumpt instrument. IKKE "pull rank". DO velkommen til at gennemgå og kritisere dine løsninger lige så meget, som du opfordrer til det på andres arbejde.
• OVERVEJ at tilføje en GitHub-integration til dit teams Slack-kanal. Det kan være en hjælp til bedre at sætte review-anmodninger på reviewernes radar, men afhængigt af den samlede mængde i din kanal er det måske ikke det rigtige for dit team.

Medlem af teamet

• Deltag i kodegennemgang. Det er ikke acceptabelt ikke at gennemgå kode.
• HUSK at lave dine kodegennemgange: dine holdkammerater er afhængige af, at du gør fremskridt med deres arbejde!
• Hvis du absolut ikke kan lave en bestemt anmeldelse, DO kommunikere det klart og åbent.
• Men.., IKKE antage, at du ikke kan lave et bestemt review, fordi du ikke kender det modul/den side af systemet/den forretningslogiske specifikation. Kodegennemgang er en vigtig læringsmulighed.
• Hvis du føler, at du ikke ved nok om noget til at lave en anmeldelse, DO Spørg forfatteren om det: De vil med glæde forklare, hvad ændringerne skal gøre.
• IKKE afvise anmeldelser baseret på erfaringsniveau (dit eller forfatterens).
• DO Prøv at gennemgå mindst lige så mange PR'er, som du producerer. Ideelt set skal forholdet mellem antal givne anmeldelser og antal krævede anmeldelser være over 1 (især i større teams).

Forfatter

• DO forstå, at det er dit ansvar at få din kode gennemgået - dit team leder måske proaktivt efter pull requests til gennemgang, men det behøver de ikke.
• IKKE altid tildele/anmode om anmeldelser fra de samme teammedlemmer - du får mere ud af en varieret anmeldergruppe (og omvendt vil en bredere vifte af udviklere få gavn af at gennemgå din kode).
• IKKE udelukke nogen fra review baseret på erfaring. Junior-udviklere har gavn af at gennemgå kode. Seniorudviklere har gavn af at gennemgå kode. Som der står i forordet til dette dokument, alle fordele ved at gennemgå kode.
• OVERVEJER bruge en randomizer til at vælge dine anmeldere. F.eks. i Ruby, %w[holdkammerat1 holdkammerat2 holdkammerat3].sample kan gøre underværker.
• DO Tildel mindst to korrekturlæsere til dine pull requests, medmindre det er helt umuligt. På den måde får flere gavn af processen (og med tre personer er det sværere at nå frem til uafgjort).
• DO Vær lydhør i dine pull requests. Selvom du ikke skal bryde dit flow for at svare på kommentarer med det samme, skal du sørge for at svare i tide - ellers vil dine PR'er blive hængende i kodegennemgang på ubestemt tid.
• DO Medbring en åben holdning. Gå altid ud fra, at din anmelder prøver at hjælpe med de bedste intentioner. Forklar din logik, gå i rette med anmelderens argumenter og besvar deres spørgsmål.
• DO Vær høflig. Misforståelser sker, men de behøver ikke at komme ud af kontrol og skade stemningen i teamet.
• DO Vær ærlig. Hvis du mener, at dette er den bedste løsning, så sig det, og fremlæg dine argumenter. Hvis du bliver overbevist om, at din reviewers forslag er bedre end det, du har lavet, så sig det til dem. Hvis du mener, at der kan produceres en "det bedste fra begge verdener"-løsning med både dine og din anmelders idéer, så foreslå dem det. I sidste ende skal du arbejde hen imod en konsensus i dine pull requests.
• DO Overlad det til din korrekturlæser at løse deres kommentarer - lad være med bare at løse dem, fordi du er overbevist om, at det er fint nu.
• DO Forklar aktivt din opgave, dine overvejelser og andre krav til dine bedømmere. Det er i orden ikke at vide - det er ikke acceptabelt at tilbageholde viden.
• IKKE antager, at du ved alt - vi er alle fantastiske specialister, men det er vigtigt at medbringe en vis portion ydmyghed i arbejdet med dig.
• DO Vær den første anmelder af din kode. Tag en anmelderhat på, og scan koden omhyggeligt, som du ville gøre med den person, du ikke bryder dig mest om. Identificer og fjern de mest åbenlyse ting, som tomme linjer, rester eller manglende specifikationer. Spring ikke noget over - det vil højst sandsynligt blive påpeget alligevel. Spild ikke korrekturlæsernes tid!
• DO Beskriv din pull request grundigt. Beskrivelse er godt, når reviewer ikke bliver overrasket over noget, mens han læser koden. Husk, at han ikke kan læse dine tanker. Derfor er det vigtigt at beskrive ting, der ikke er indlysende, vigtige beslutninger med begrundelse eller alle nye klasser og filer.
• OVERVEJER ved hjælp af pull request-skabelonen. Hvis du bruger Github, skal du tilføje det til dit repository under .github/pull_request_template.md. Det opfordrer alle teammedlemmer til at beskrive deres pull requests. Det er også meget nemmere at skrive, når du har udfyldt beskrivelsesfeltet med en skabelon. Her kan du finde en skabelon, som vi bruger i et af vores projekter https://gist.github.com/weemanjz/a20ccb9f3f492b9bd21ab026a1d46353

Forfatter

• DO forstår, at det er dit ansvar at have din Kodegennemgang - Dit team leder måske proaktivt efter pull requests til gennemgang, men det behøver de ikke.
• IKKE altid tildele/anmode om anmeldelser fra den samme kode-reviewere - du får mere ud af en varieret anmelderpulje (og omvendt vil en bredere vifte af udviklere få gavn af at anmelde din kode)
• IKKE udelukke nogen fra gennemgang baseret på erfaring. Juniorudviklere nyder godt af at udføre Kodeanmeldelser. Seniorudviklere nyder godt af at udføre Kodeanmeldelser. Som der står i forordet til dette dokument, alle fordele ved at optræde Kodeanmeldelser.

Anmelder

• DO Brug sproget med forslag i stedet for krav. I stedet for at sige "Du burde forbedre kodekvaliteten ved at gøre X i stedet", siger "Har du overvejet at forbedre Kodekvalitet ved at gøre X?"
• DO forklare dine forslag. "Jeg tror, at X er bedre her, fordi det hjælper på overførsel af viden og forbedring af kodekvaliteten."
• Selv hvis dit forslag kommer fra objektive kilder (f.eks. Kodestil retningslinjer), DO bede forfatteren om at gøre noget i stedet for at fortælle dem, at de skal gøre noget. "Hold venligst alle widgets frobbede i henhold til vores Kodestil guide - [link]"
• IKKE antage, at du ved alt. "Jeg har forstået, at denne widget aldrig bør frobikke, og under disse forhold vil den gøre det - er det en undtagelse, der kræver en Kodegennemgang?"
• DO Brug et inkluderende sprog. "Jeg tror, vi ville være bedre stillet i fremtiden, hvis vi byggede det sådan her. Hvad synes du om det her? bedre gennemgang af kode forslag?" og "Måske skulle vi bruge X her i stedet for en effektiv kodegennemgang?"
• DO være hurtig til at gøre din Kodeanmeldelser. Du skal ikke bryde dit flow for at lave dem, men prøv at holde loopet stramt, hvis det er muligt. Nogle mennesker kan lide at lave dem enten i begyndelsen eller slutningen af deres arbejdsdag, enten som "opvarmning" eller "nedkøling".

Bemærk, at disse nøgleord er indsat på en måde, så tekstens kontekst og sammenhæng bevares. Hvis du gerne vil have dem indsat bestemte steder, bedes du angive det.