Koodin tarkistuksen parhaat käytännöt

Kirjoittaja hyötyvät siitä, että he saavat erilaisen näkökulman tehtäväänsä ja koodi. He oppivat usein uusia temppuja tai löytävät mahdollisesti optimaalisemman tavan ratkaista tietty ongelma. He myös ottavat muutoskokonaisuutensa käyttöön luottavaisin mielin tietäen, että muut ovat tarkistaneet koodin oikeellisuuden ja todenneet, että kaikki on kunnossa.

Arvostelija hyötyy siitä, että näkee erilaisia lähestymistapoja ongelmanratkaisuun käytännössä. He myös parantavat koodinlukutaitojaan, mikä on erittäin tärkeää, kun he sukeltavat esimerkiksi kirjastoon, jota arvioidaan käytettäväksi projekti. Koodin tarkastelu on myös oppimismahdollisuus niin tarkastelijalle kuin kirjoittajallekin: he saattavat oppia uusia temppuja.

The joukkue kokonaisuutena hyötyy, koska tietyn ongelman ratkaisun tarkastelu edellyttää ongelman ymmärtämistä ainakin korkealla abstraktiotasolla. Tämä auttaa purkamaan tiimissä mahdollisesti esiintyviä tahattomia tietosiiloja. Se lisää myös "bussitekijää": koska vähintään kaksi ihmistä (mieluiten useampi) on tietoinen tietystä muutoksesta, on epätodennäköisempää, että kukaan tiimissä ei tiedä, miten moduulia päivitetään tai miksi jokin tietty vika saattaa esiintyä.

Asiakas hyötyy nopeasti ja luotettavasti käyttöönotetuista muutoksista ja ratkaisuista. Yhdessä muiden parhaiden käytäntöjen kanssa (kuten hyvä testikattavuus, CI/CD, staging-ympäristöt jne.) koodikatselmuksilla varmistetaan myös, että käyttöönotettavat muutokset ovat turvallisia, järkeviä ja täyttävät vaatimukset määritellyllä tavalla.

Näiden ohjeiden tarkoitus ja käyttö

Muistakaa, että näiden ehdotusten tarkoituksena on ennen kaikkea luoda ympäristö, joka edistää kunnianhimoista ja tehokasta ongelmanratkaisua, ja samalla luoda turvaverkko sekä edistää luottamusta ja avoimuutta tiimin jokaisessa jäsenessä.

Vaikka on erittäin suositeltavaa, että joukkue noudattaa näitä ohjeita, niitä ei ole tarkoitettu koviksi ja sitoviksi säännöiksi. Näitä puitteita ei myöskään ole tarkoitettu täsmällisesti noudatettavaksi "prosessiksi", sillä jäykät prosessit yleensä vähentävät nopeutta ja edistävät tuhlausta.

Olet enemmän kuin tervetullut rakentamaan näitä ohjeita tiimissäsi. Muista kuitenkin, että kun kehittäjät vaihtuvat tiimien välillä, he odottavat, että koodin tarkistus perustuu edelleen tähän asiakirjaan kaikissa tiimeissä, joihin he liittyvät. Pidä kaikki lisäsäännöt dokumentoituna ja palauta tähän asiakirjaan parannuksia, jotka ovat toimineet poikkeuksellisen hyvin.

Koodin tarkistamiseen liittyvät tehtävät

Jokaisella tiimin jäsenellä on tietyt vastuut koodin tarkistamisen suhteen. Seuraavassa esitetään koodin tarkasteluun liittyviä ohjeita ja kieltoja prosessin roolin mukaan.

Hankkeen johtaja

• DO varmista, että arkistosi ovat hyvin konfiguroituja (esim. sulautukset tuotantoon suuntautuvaan haaraan eivät ole sallittuja ilman vähintään yhtä hyväksyvää tarkistusta).
• DO Varmista, että tiimisi ymmärtää ja soveltaa näitä käytäntöjä, ja tee aktiivisesti työtä sen eteen, että ymmärretään, miksi teemme asioita tietyllä tavalla.
• DO varo tasapelitilanteita, joissa vastakkaisia mielipiteitä ei voida ratkaista: tiimisi teknisenä johtajana sinun vastuullasi on valita tällaisissa tapauksissa tarkoituksenmukaisempi ratkaisu ja pitää työ etenemässä.
• Kuitenkin, ÄLÄ käyttää projektijohtamista tylppänä välineenä. ÄLÄ "pull rank". DO toivottaa tervetulleeksi ratkaisujesi tarkastelun ja kritiikin yhtä lailla kuin kannustat niitä muidenkin töiden osalta.
• HARKITSE GitHub-integraation lisäämistä tiimisi Slack-kanavaan. Siitä voi olla apua, jotta tarkistuspyynnöt saadaan paremmin arvioijien tietoisuuteen, mutta kanavasi yleisestä volyymista riippuen tämä voi olla tiimillesi sopiva vaihtoehto.

Tiimin jäsen

• OSALLISTU koodikatselmuksiin. Ei ole hyväksyttävää olla tarkistamatta koodia.
• Muista tehdä koodikatselmukset: joukkuetoverisi ovat riippuvaisia siitä, että heidän työnsä etenee!
• Jos et missään nimessä voi tehdä tiettyä tarkistusta, DO viestiä siitä selkeästi ja avoimesti.
• Kuitenkin, ÄLÄ olettaa, että et voi tehdä tiettyä tarkistusta, koska et tunne kyseistä moduulia/järjestelmän/liiketoimintalogiikan osaa. Koodin tarkistaminen on tärkeä oppimismahdollisuus.
• Jos sinusta tuntuu, ettet tiedä tarpeeksi jostakin asiasta tehdäkseni arvostelun, DO Kysy asiasta kirjoittajalta: hän selittää mielellään, mitä muutoksilla on tarkoitus tehdä.
• ÄLÄ evätä arvostelut kokemuksen tason perusteella (sinun tai kirjoittajan).
• DO yritä tarkistaa vähintään yhtä monta PR:ää kuin tuotat. Ihannetapauksessa annettujen arvostelujen ja vaadittujen arvostelujen suhde on yli 1 (erityisesti suuremmissa tiimeissä).

Kirjoittaja

• DO ymmärrä, että on sinun vastuullasi, että koodisi tarkistetaan - tiimisi saattaa etsiä aktiivisesti tarkistettavia pull-pyyntöjä, mutta heidän ei tarvitse.
• ÄLÄ anna/pyydä arviointeja aina samoilta tiimin jäseniltä - saat enemmän hyötyä monipuolisesta arvioijapoolista (ja päinvastoin, laajempi joukko kehittäjiä hyötyy koodisi arvioinnista).
• ÄLÄ sulkea joku pois arvioinnista kokemuksen perusteella. Nuoremmat kehittäjät hyötyvät koodin tarkistamisesta. Vanhemmat kehittäjät hyötyvät koodin tarkistamisesta. Kuten tämän asiakirjan esipuheessa todetaan, kaikki hyötyy koodin tarkistamisesta.
• HARKITSE käyttämällä satunnaistoimintoa arvostelijoiden valinnassa. Esimerkiksi Rubyssä, %w[joukkuetoveri1 joukkuetoveri2 joukkuetoveri3].sample voi tehdä ihmeitä.
• DO määritä vähintään kaksi arvioijaa julkaisupyyntöihisi, ellei se ole täysin mahdotonta. Näin useampi ihminen hyötyy prosessista (ja kolmen ihmisen kanssa on vaikeampi päästä tasapeliin).
• DO ole reagoiva pull-pyynnöissäsi. Vaikka sinun ei pitäisi rikkoa virtaa vastataksesi juuri nyt kaikkiin kommentteihin, varmista, että vastauksesi ovat oikea-aikaisia - muutoin PR-ilmoituksesi viipyvät koodin tarkistuksessa loputtomiin.
• DO tuo avoin asenne. Oleta aina, että arvioija yrittää auttaa parhain päin. Selitä logiikkasi, puutu arvostelijan väitteisiin ja vastaa hänen kysymyksiinsä.
• DO Ole kohtelias. Väärinkäsityksiä sattuu, mutta niiden ei tarvitse riistäytyä käsistä ja vahingoittaa tiimin ilmapiiriä.
• DO Ole rehellinen. Jos uskotte, että tämä on paras ratkaisu, sanokaa se ja esittäkää perustelut. Jos olet vakuuttunut siitä, että arvioijasi ehdotukset ovat parempia kuin tuottamasi, kerro niistä. Jos uskot, että sekä sinun että arvioijasi ideoita hyödyntävä ratkaisu on paras mahdollinen, ehdota sitä arvioijallesi. Viime kädessä, pyrkikää yhteisymmärrykseen vetoomuksissanne.
• DO jätä heidän kommenttiensa ratkaiseminen tarkastajan tehtäväksi - älä ratkaise niitä vain siksi, että olet vakuuttunut siitä, että asia on nyt kunnossa.
• DO selitä aktiivisesti tehtäväsi, perustelusi ja muut vaatimukset arvioijillesi. On hyvä olla tietämättä - ei ole hyväksyttävää salata tietoa.
• ÄLÄ olettaa tietävänsä kaiken - me kaikki olemme mahtavia asiantuntijoita, mutta on tärkeää tuoda tietty määrä nöyryyttä työskentelyyn kanssasi.
• DO olla koodisi ensimmäinen tarkastaja. Pue arvostelijan hattu päähäsi ja skannaa koodi huolellisesti, kuten tekisit sen henkilön kohdalla, josta et enimmäkseen pidä. Tunnista ja poista ilmeisimmät asiat, kuten tyhjät rivit, mahdolliset ylijäämät tai puuttuvat speksit. Älä jätä mitään pois - siitä huomautetaan todennäköisesti joka tapauksessa. Älä tuhlaa tarkastajien aikaa!
• DO kuvaile perusteellisesti vetopyyntöäsi. Kuvaus on hyvä, kun arvioija ei ylläty mistään koodia lukiessaan. Muista, että hän ei voi lukea ajatuksiasi. Siksi on tärkeää kuvata asiat, jotka eivät ole itsestään selviä, keskeiset päätökset syineen tai kaikki uudet luokat ja tiedostot.
• HARKITSE käyttämällä pull request -mallia. Jos käytät Githubia, lisää se arkistoosi osoitteessa .github/pull_request_template.md. Se kannustaa kaikkia tiimin jäseniä kuvaamaan vetopyyntöjään. Kirjoittaminen on myös paljon helpompaa, kun kuvauskenttä on täytetty mallilla. Täältä löydät mallin, jota käytämme yhdessä projektissamme. https://gist.github.com/weemanjz/a20ccb9f3f492b9bd21ab026a1d46353

Kirjoittaja

• DO ymmärtää, että on sinun vastuullasi, että koodin tarkistus - tiimisi saattaa etsiä proaktiivisesti tarkistettavia pyyntöjä, mutta heidän ei tarvitse.
• ÄLÄ antaa/pyytää arviointeja aina samalta taholta. koodintarkistajat - saat enemmän hyötyä monipuolisesta arvostelijapoolista (ja päinvastoin, laajempi joukko kehittäjiä hyötyy koodisi arvostelusta).
• ÄLÄ sulkea joku pois arvioinnista kokemuksen perusteella. Nuoremmat kehittäjät hyötyvät suorittamalla koodiarvostelut. Vanhempi kehittäjät hyötyvät suorittamalla koodiarvostelut. Kuten tämän asiakirjan esipuheessa todetaan, kaikki suorituksista saatava hyöty koodiarvostelut.

Arvostelija

• DO käyttää ehdotusten kieltä vaatimusten sijaan. Sen sijaan, että sanoisit "Sinun pitäisi parantaa koodin laatua tekemällä sen sijaan X", sanotaan "Oletko harkinnut parantaa koodin laatu tekemällä X?"
• DO selitä ehdotuksesi. "Mielestäni X on parempi täällä, koska se auttaa siinä. tiedonsiirto ja koodin laadun parantaminen."
• Vaikka ehdotuksesi tulisikin objektiivisista lähteistä (esim. koodityyli suuntaviivat), DO pyydä kirjoittajaa tekemään jotakin sen sijaan, että käsket häntä tekemään jotakin. "Pidä kaikki widgetit frobnicated kuten per meidän koodityyli opas - [linkki]"
• ÄLÄ olettaa, että tiedät kaiken. "Ymmärtääkseni tämän widgetin ei pitäisi koskaan frobnicata, ja näissä olosuhteissa se frobnicaa - onko tämä poikkeus, joka tarvitsee koodin tarkistus?"
• DO käyttää osallistavaa kieltä. "Uskon, että meillä olisi tulevaisuudessa parempi olla, jos rakentaisimme tämän näin. Mitä mieltä olet tästä parempi koodin tarkistus ehdotus?" ja "Ehkä meidän pitäisi käyttää X:ää tässä sen sijaan, että saisimme tehokas koodin tarkastelu?"
• DO toimimaan ripeästi koodiarvostelut. Sinun ei pitäisi katkaista virtaustasi niiden tekemiseen, mutta yritä pitää silmukka tiukkana, jos mahdollista. Jotkut haluavat tehdä niitä joko työpäivän alussa tai lopussa, joko "lämmittelynä" tai "jäähdyttelynä".

Huomaa, että nämä avainsanat on lisätty siten, että tekstin asiayhteys ja johdonmukaisuus säilyvät ennallaan. Jos haluatte ne johonkin tiettyyn kohtaan, pyydämme ystävällisesti täsmentämään.