Beste praksis for kodegjennomgang

Forfatteren av å få et annet perspektiv på oppgaven sin, og det er kode. De vil ofte lære nye triks eller oppdage en potensielt mer optimal måte å løse et bestemt problem på. De vil også distribuere endringene sine med selvtillit, vel vitende om at andre har sjekket koden for å se om den er korrekt, og at de er enige om at alt er i orden.

Anmelderen drar nytte av å se ulike tilnærminger til problemløsning i praksis. De vil også bli flinkere til å lese kode, noe som er svært viktig når man dykker ned i f.eks. et bibliotek som evalueres for bruk i en prosjekt. Kodegjennomgang er også en mulighet til å lære, både for den som gjennomgår koden, og for forfatteren.

Den team som helhet, siden det å vurdere en løsning på et bestemt problem krever at man forstår problemet på et høyt abstraksjonsnivå. Dette bidrar til å rive ned eventuelle utilsiktede kunnskapssiloer som kan oppstå i et team. Det vil også øke "bussfaktoren": Fordi minst to personer (helst flere) er klar over en gitt endring, er det mindre sannsynlighet for en situasjon der ingen i teamet vet hvordan en modul skal oppdateres, eller hvorfor en bestemt feil kan oppstå.

Kunden drar nytte av endringer og løsninger som distribueres raskt og trygt. Sammen med andre beste praksiser (som god testdekning, CI/CD, staging-miljøer osv.) sikrer kodegjennomgang også at det som distribueres, er trygt, fornuftig og oppfyller kravene som er spesifisert.

Hensikt og bruk av disse retningslinjene

Husk at disse forslagene først og fremst er ment å skape et miljø som bidrar til ambisiøs og effektiv problemløsning, samtidig som de skaper et sikkerhetsnett og fremmer tillit og åpenhet hos alle teammedlemmer.

Selv om det anbefales på det sterkeste at et team følger disse retningslinjene, er de ikke ment som absolutte regler. Rammeverket er heller ikke ment som en "prosess" som skal følges til punkt og prikke, ettersom rigide prosesser har en tendens til å redusere hastigheten og fremme sløsing.

Du er hjertelig velkommen til å bygge videre på disse retningslinjene i teamet ditt. Husk imidlertid at når utviklere roterer mellom teamene, vil de forvente at kodegjennomgangen i teamene de blir en del av, fortsatt er basert på dette dokumentet. Sørg for at eventuelle tilleggsregler dokumenteres, og bidra til dette dokumentet med forbedringer som har fungert spesielt godt.

Ansvarsområder rundt kodegjennomgang

Alle i teamet har et visst ansvar når det gjelder kodegjennomgang. Nedenfor følger en oversikt over hva man bør og ikke bør gjøre i forbindelse med kodegjennomgang, fordelt på de ulike rollene i prosessen.

Prosjektleder

• DO sørge for at repositoriene er godt konfigurert (f.eks. at sammenslåinger til produksjonsgrenen ikke er tillatt uten minst én godkjennende gjennomgang).
• DO Sørg for at teamet ditt forstår og bruker disse rutinene, og arbeid aktivt for å fremme forståelse for hvorfor vi gjør ting på en bestemt måte.
• DO Vær oppmerksom på uavklarte situasjoner der motstridende meninger ikke kan løses: Som teknisk leder for teamet ditt er det ditt ansvar å velge den mest relevante løsningen i slike tilfeller og sørge for at arbeidet går fremover.
• Men.., IKKE bruke prosjektledelse som et sløvt virkemiddel. IKKE "trekk rang". DO Du er like velkommen til å vurdere og kritisere løsningene dine som du oppmuntrer til å kritisere andres arbeid.
• VURDER å legge til en GitHub-integrasjon i teamets Slack-kanal. Det kan være nyttig for å gjøre gjennomgangsforespørsler mer synlige for korrekturleserne, men avhengig av det totale volumet i kanalen din, er det ikke sikkert at dette er riktig for teamet ditt.

Medlem av teamet

• DELTA i kodegjennomganger. Det er ikke akseptabelt å ikke gjennomgå kode.
• Husk å gjøre kodegjennomgangene dine: lagkameratene dine er avhengige av at du gjør fremgang i arbeidet deres!
• Hvis du absolutt ikke kan gjøre en bestemt anmeldelse, DO kommunisere det tydelig og åpent.
• Men.., IKKE anta at du ikke kan gjøre en bestemt gjennomgang fordi du ikke kjenner den modulen/den siden av systemet/forretningslogikkspesifikasjonen. Kodegjennomgang er en viktig læringsmulighet.
• Hvis du føler at du ikke vet nok om noe til å skrive en anmeldelse, DO spør forfatteren om det: de forklarer gjerne hva endringene er ment å gjøre.
• IKKE avslå anmeldelser basert på erfaringsnivå (din eller forfatterens).
• DO prøv å gjennomgå minst like mange PR-er som du produserer. Ideelt sett bør forholdet mellom antall anmeldelser og antall påkrevde anmeldelser være over 1 (spesielt i større team).

Forfatter

• DO forstå at det er ditt ansvar å få koden din gjennomgått - teamet ditt leter kanskje proaktivt etter pull-forespørsler som skal gjennomgås, men de trenger ikke å gjøre det.
• IKKE alltid tildele/be om gjennomganger fra de samme teammedlemmene - du vil ha større nytte av et variert utvalg av korrekturlesere (og omvendt vil et bredere spekter av utviklere ha nytte av å se gjennom koden din)
• IKKE utelukke noen fra gjennomgang basert på erfaring. Juniorutviklere drar nytte av å gjennomgå kode. Seniorutviklere drar nytte av å gjennomgå kode. Som nevnt i forordet til dette dokumentet, alle fordeler ved å gjennomgå kode.
• VURDERER ved hjelp av en randomizer for å velge anmeldere. F.eks. i Ruby, %w[lagkamerat1 lagkamerat2 lagkamerat3].sample kan gjøre underverker.
• DO tilordne minst to korrekturlesere til pull-forespørsler, med mindre det er helt umulig. På den måten får flere nytte av prosessen (og med tre personer er det vanskeligere å komme frem til uavgjort).
• DO Vær responsiv i dine pull-forespørsler. Selv om du ikke bør bryte flyten for å svare på kommentarer med en gang, må du sørge for at du svarer i tide - ellers vil PR-ene dine bli liggende i kodegjennomgang på ubestemt tid.
• DO Ha en åpen holdning. Gå alltid ut fra at anmelderen prøver å hjelpe deg med de beste intensjoner. Forklar logikken din, gå i rette med anmelderens argumenter og svar på spørsmålene deres.
• DO Vær høflig. Misforståelser skjer, men de trenger ikke å komme ut av kontroll og skade stemningen i teamet.
• DO Vær ærlig. Hvis du mener at dette er den beste løsningen, så si det og legg frem argumentene dine. Hvis du blir overbevist om at korrekturleserens forslag er bedre enn det du har kommet frem til, må du si det. Hvis du mener at det er mulig å lage en "det beste fra begge verdener"-løsning med både dine og korrekturleserens ideer, foreslå det for dem. Til syvende og sist må du jobbe mot konsensus i dine pull-forespørsler.
• DO Overlat det til anmelderen å løse kommentarene deres - ikke bare løs dem fordi du er overbevist om at det er i orden nå.
• DO Forklar aktivt oppgaven din, begrunnelsen din og andre krav til sensorene dine. Det er greit å ikke vite - det er ikke akseptabelt å holde tilbake kunnskap.
• IKKE anta at du vet alt - vi er alle fantastiske spesialister, men det er viktig å ta med seg en viss ydmykhet inn i arbeidet med deg.
• DO Vær den første korrekturleseren av koden din. Ta på deg en korrekturleserhatt og skann koden nøye, akkurat som du ville gjort med en person du ikke liker så godt. Identifiser og eliminer de mest åpenbare tingene, som tomme linjer, rester eller manglende spesifikasjoner. Ikke hopp over noe - det vil mest sannsynlig bli påpekt uansett. Ikke kast bort tiden til korrekturleserne!
• DO beskriv pull-forespørselen din grundig. Beskrivelse er bra når anmelderen ikke blir overrasket over noe når han leser koden. Husk at han ikke kan lese tankene dine. Derfor er det viktig å beskrive ting som ikke er åpenbare, viktige beslutninger med begrunnelse eller alle nye klasser og filer.
• VURDERER ved hjelp av pull request-malen. Hvis du bruker Github, legger du det til i depotet ditt under .github/pull_request_template.md. Det oppmuntrer alle teammedlemmer til å beskrive pull-forespørslene sine. Det er også mye enklere å skrive når du har et beskrivelsesfelt som er fylt ut med en mal. Her finner du en mal som vi bruker i et av prosjektene våre https://gist.github.com/weemanjz/a20ccb9f3f492b9bd21ab026a1d46353

Forfatter

• DO forstår at det er ditt ansvar å ha din kodegjennomgang - teamet ditt leter kanskje proaktivt etter pull-forespørsler som skal gjennomgås, men det trenger de ikke.
• IKKE alltid tildele/be om anmeldelser fra samme kodegranskere - du vil ha større nytte av en variert gruppe korrekturlesere (og omvendt vil et bredere spekter av utviklere ha nytte av å se gjennom koden din)
• IKKE utelukke noen fra vurdering basert på erfaring. Juniorutviklere drar nytte av å utføre kodeanmeldelser. Seniorutviklere drar nytte av å utføre kodeanmeldelser. Som nevnt i forordet til dette dokumentet, alle fordeler ved å utføre kodeanmeldelser.

Anmelder

• DO Bruk et språk som er et forslag i stedet for et krav. I stedet for å si "Du burde forbedre kodekvaliteten ved å gjøre X i stedet", sier "Har du vurdert å forbedre kodekvalitet ved å gjøre X?"
• DO forklare forslagene dine. "Jeg tror X er bedre her, fordi det hjelper i kunnskapsoverføring og forbedre kodekvaliteten."
• Selv om forslaget ditt kommer fra objektive kilder (f.eks. kodestil retningslinjer), DO be forfatteren om å gjøre noe i stedet for å be dem om å gjøre noe. "Vennligst hold alle widgets frobnikert i henhold til våre kodestil guide - [lenke]"
• IKKE anta at du vet alt. "Jeg har forstått det slik at denne widgeten aldri skal frobnikere, og under disse forholdene vil den gjøre det - er dette et unntak som trenger en kodegjennomgang?"
• DO bruke et inkluderende språk. "Jeg tror vi ville hatt det bedre i fremtiden hvis vi bygget dette på denne måten. Hva synes du om dette bedre kodegjennomgang forslag?" og "Kanskje vi burde bruke X her i stedet for en effektiv kodegjennomgang?"
• DO være rask med å gjøre dine kodeanmeldelser. Du bør ikke bryte flyten for å gjøre dem, men prøv å holde løkken tett hvis det er mulig. Noen liker å gjøre dem enten i begynnelsen eller slutten av arbeidsdagen, enten som "oppvarming" eller "nedkjøling".

Vær oppmerksom på at disse nøkkelordene er satt inn på en slik måte at sammenhengen i teksten bevares. Hvis du ønsker dem på bestemte steder, vennligst spesifiser det.