Geriausia kodo peržiūros praktika

Autorius naudos iš kitokio požiūrio į savo užduotį ir kodas. Jie dažnai išmoksta naujų gudrybių arba atranda optimalesnį tam tikros problemos sprendimo būdą. Be to, jie drąsiai įdiegs savo pakeitimų rinkinį, žinodami, kad kiti žmonės patikrino kodo teisingumą ir sutarė, kad viskas yra gerai.

Recenzentas naudos iš to, kad pamatysite skirtingus problemų sprendimo būdus. Jie taip pat patobulins kodo skaitymo įgūdžius, o tai labai svarbu, kai gilinamasi į, pvz., biblioteką, vertinamą naudoti projektas. Kodo peržiūra taip pat yra mokymosi galimybė ne tik autoriui, bet ir recenzentui: jis taip pat gali išmokti naujų gudrybių.

Svetainė komanda naudą, nes tam tikros problemos sprendimo peržiūra reikalauja suprasti problemą bent jau aukštu abstrakcijos lygiu. Tai padeda sugriauti bet kokias atsitiktines žinių silosines, kurios gali atsirasti team. Tai taip pat padidins “autobuso veiksnį”: kadangi apie tam tikrą pakeitimą žino bent du žmonės (pageidautina, kad daugiau), mažesnė tikimybė, kad susidarys situacija, kai nė vienas team narys nežinos, kaip atnaujinti modulį arba kodėl gali atsirasti tam tikra klaida.

Klientas naudos iš greitai ir užtikrintai diegiamų pakeitimų ir sprendimų. Kartu su kitomis geriausiomis praktikomis (pvz., puiki testavimo aprėptis, CI/CD, etapinės aplinkos ir kt.) kodo peržiūros taip pat užtikrina, kad tai, kas diegiama, yra saugu, protinga ir atitinka nurodytus reikalavimus.

Šių gairių paskirtis ir naudojimas

Atminkite, kad visų pirma šiais pasiūlymais siekiama sukurti ambicingam ir veiksmingam problemų sprendimui palankią aplinką, kartu sukuriant saugumo tinklą ir skatinant kiekvieno team nario pasitikėjimą bei skaidrumą.

Nors labai rekomenduojama, kad team laikytųsi šių gairių, jos nėra griežtos taisyklės. Ši sistema taip pat nėra skirta kaip “procesas”, kurio reikia tiksliai laikytis, nes griežti procesai paprastai mažina greitį ir skatina švaistymą.

Galite remtis šiomis gairėmis savo team. Tačiau nepamirškite, kad kūrėjams keičiant team, jie tikėsis, kad bet kurioje team, prie kurios jie prisijungia, kodo peržiūra vis tiek bus pagrįsta šiuo dokumentu. Saugokite dokumentuose užfiksuotas papildomas taisykles ir į šį dokumentą įtraukite patobulinimus, kurie itin gerai pasiteisino.

Atsakomybė už kodo peržiūrą

Kiekvienas team narys turi tam tikrų pareigų, susijusių su kodo peržiūra. Toliau tam tikri kodo peržiūros "do" ir "ne" principai išdėstyti pagal vaidmenį šiame procese.

Projekto vadovas

• DO užtikrinti, kad jūsų saugyklos būtų gerai sukonfigūruotos (pvz., neleidžiama sujungti į gamybai skirtą šaką be bent vienos patvirtinančios peržiūros).
• DO užtikrinti, kad jūsų team suprastų ir taikytų šią praktiką, ir aktyviai siekti, kad būtų suprantama, kodėl mes elgiamės tam tikru būdu.
• DO atkreipkite dėmesį į bet kokias lygiavertes situacijas, kai negalima išspręsti priešingų nuomonių: kaip team techninis vadovas tokiais atvejais privalote pasirinkti tinkamesnį sprendimą ir toliau tęsti darbą.
• Tačiau, NEGALIMA naudoti vadovavimą projektui kaip bukas įrankis. NEGALIMA “traukimo rangas”. DO palankiai vertinti ir kritikuoti savo sprendimus taip pat, kaip skatinate juos vertinti bet kurio kito žmogaus darbą.
• SUSIMĄSTYKITE, ar į savo team ’Slack" kanalą nepridėsite "GitHub" integracijos. Tai gali būti naudinga, kad peržiūros užklausos būtų geriau matomos recenzentams, tačiau, priklausomai nuo bendro jūsų kanalo kiekio, tai gali būti tinkama arba netinkama jūsų team.

Komandos narys

• Dalyvaukite kodo peržiūrose. Neperžiūrėti kodo nepriimtina.
• Nepamirškite atlikti kodo peržiūrų: jūsų team bendražygiai priklauso nuo jūsų, nes nuo jūsų priklauso jų darbo pažanga!
• Jei tikrai negalite atlikti tam tikros peržiūros, DO aiškiai ir atvirai apie tai pranešti.
• Tačiau, NEGALIMA daryti prielaidą, kad negalite atlikti tam tikros peržiūros, nes neišmanote to modulio / sistemos dalies / verslo logikos specifikacijos. Kodo peržiūra yra svarbi mokymosi galimybė.
• Jei manote, kad apie ką nors žinote nepakankamai, kad galėtumėte parengti apžvalgą, DO paklauskite apie tai autoriaus: jis mielai paaiškins, ką reikia keisti.
• NEGALIMA neigti atsiliepimus pagal patirties lygį (jūsų arba autoriaus).
• DO pasistenkite peržiūrėti bent tiek pat PR, kiek jų parengėte. Geriausia, jei jūsų pateiktų ir reikalingų peržiūrų santykis būtų didesnis nei 1 (ypač didesnių team).

Autorius

• DO supraskite, kad už savo kodo peržiūrą esate atsakingi patys - jūsų team gali aktyviai ieškoti prašymų peržiūrėti, bet neprivalo.
• NEGALIMA visada skirkite/prašykite, kad peržiūrą atliktų tie patys team nariai - turėsite daugiau naudos iš įvairaus recenzentų rato (ir atvirkščiai, jūsų kodo peržiūra bus naudinga platesniam programuotojų ratui).
• NEGALIMA neleisti kam nors dalyvauti peržiūroje remiantis patirtimi. Jaunesniesiems programuotojams naudinga peržiūrėti kodą. Vyresniesiems programuotojams naudinga peržiūrėti kodą. Kaip teigiama šio dokumento įžangoje, visi naudos iš kodo peržiūros.
• ATSIŽVELKITE Į naudodami atsitiktinės atrankos priemonę atrinkti recenzentus. Pvz. Ruby, %w[teammate1 teammate2 teammate3].sample gali daryti stebuklus.
• DO priskirkite bent du recenzentus savo traukimo užklausoms, nebent tai visiškai neįmanoma. Taip procesas bus naudingas daugiau žmonių (o su trimis žmonėmis bus sunkiau pasiekti lygiąsias).
• DO reaguokite į užklausas. Nors neturėtumėte nutraukti savo srauto, kad atsakytumėte į bet kokias pastabas, tačiau įsitikinkite, kad atsakymai pateikiami laiku - kitaip jūsų PR užtruks kodo peržiūroje neribotą laiką.
• DO būkite atviri. Visada manykite, kad recenzentas stengiasi padėti turėdamas geriausių ketinimų. Paaiškinkite savo logiką, atkreipkite dėmesį į recenzento argumentus ir atsakykite į jo klausimus.
• DO būkite mandagūs. Nesusipratimų pasitaiko, bet jie neturi tapti nekontroliuojami ir pakenkti team atmosferai.
• DO būkite sąžiningi. Jei manote, kad tai geriausias sprendimas, pasakykite tai ir pateikite savo argumentus. Jei įsitikinsite, kad recenzento pasiūlymai yra geresni už tai, ką parengėte, pasakykite jiems tai. Jei manote, kad galima sukurti “geriausią iš abiejų pasaulių” sprendimą, naudojant ir jūsų, ir recenzento idėjas, pasiūlykite jam tokį sprendimą. Galiausiai savo užklausose siekite konsensuso.
• DO palikite jų pastabų sprendimą peržiūros specialistui - nespręskite jų tik todėl, kad esate įsitikinę, jog dabar viskas gerai.
• DO aktyviai paaiškinkite recenzentams savo užduotį, argumentus ir kitus reikalavimus. Gerai, kad nežinote, bet nepriimtina nuslėpti žinias.
• NEGALIMA manyti, kad viską žinote - mes visi esame puikūs specialistai, tačiau svarbu, kad į darbą su jumis ateitų tam tikras nuolankumas.
• DO būti pirmuoju savo kodo tikrintoju. Užsidėkite recenzento kepurę ir atidžiai nuskaitykite kodą taip, kaip tai darytumėte žmogui, kurio dažniausiai nemėgstate. Nustatykite ir pašalinkite akivaizdžiausius dalykus, tokius kaip tuščios eilutės, bet kokie likučiai ar trūkstamos specifikacijos. Nieko nepraleiskite - greičiausiai į tai vis tiek bus atkreiptas dėmesys. Nešvaistykite recenzentų laiko!
• DO išsamiai aprašykite savo užklausą. Aprašymas yra geras tada, kai skaitydamas kodą recenzentas nebus niekuo nustebintas. Atminkite, kad jis negali skaityti jūsų minčių. Todėl svarbu aprašyti dalykus, kurie nėra akivaizdūs, pagrindinius sprendimus ir jų priežastis arba visas naujas klases ir failus.
• ATSIŽVELKITE Į naudodami traukimo užklausos šabloną. Jei naudojate "Github", pridėkite jį į savo saugyklą po .github/pull_request_template.md. Ji skatina visus team narius aprašyti savo traukimo užklausas. Taip pat daug lengviau rašyti, kai aprašymo laukas užpildytas šablonu. Čia galite rasti šabloną, kurį naudojame viename iš savo projektų https://gist.github.com/weemanjz/a20ccb9f3f492b9bd21ab026a1d46353

Autorius

• DO supranta, kad yra jūsų atsakomybė už tai, kad jūsų kodo peržiūra - jūsų team gali aktyviai ieškoti "pull" užklausų peržiūrai, bet neprivalo.
• NEGALIMA visada priskirti ir (arba) prašyti peržiūrėti tą patį kodo peržiūrėtojai - turėsite daugiau naudos iš įvairaus recenzentų rato (ir atvirkščiai, jūsų kodą peržiūrės daugiau programuotojų).
• NEGALIMA neleisti kam nors dalyvauti peržiūroje remiantis patirtimi. Jaunesniesiems kūrėjams naudinga atlikti kodo peržiūros. Vyresniesiems kūrėjams naudinga atlikti kodo peržiūros. Kaip teigiama šio dokumento įžangoje, visi naudą, gaunamą atliekant kodo peržiūros.

Recenzentas

• DO vartoti ne reikalavimų, o pasiūlymų kalbą. Užuot sakę “Turėtumėte pagerinti kodo kokybę. vietoj to darydami X”.”, sakykime. “Ar svarstėte galimybę patobulinti kodo kokybė darydami X?”
• DO paaiškinkite savo pasiūlymus. “Manau, kad X čia geriau, nes padeda žinių perdavimas ir kodo kokybės gerinimas.”
• Net jei jūsų pasiūlymas yra iš objektyvių šaltinių (pvz. kodo stilius gairės), DO paprašykite autoriaus ką nors padaryti, užuot liepę jam ką nors daryti. “Prašome laikyti visus valdiklius frobnicated kaip pagal mūsų kodo stilius vadovas - [nuoroda]”
• NEGALIMA manyti, kad viską žinote. “Kaip suprantu, šis valdiklis niekada neturėtų frobnikatuoti, o šiomis sąlygomis jis frobnikatuos - ar tai išimtis, kuriai reikia kodo peržiūra?”
• DO naudoti įtraukią kalbą. “Manau, kad ateityje mums būtų geriau, jei taip pastatytume. Ką manote apie tai geresnė kodo peržiūra pasiūlymą?” ir “Galbūt čia turėtume naudoti X, o ne veiksminga kodo peržiūra?”
• DO skubiai atlikite savo kodo peržiūros. Jų atlikdami neturėtumėte nutraukti savo srauto, tačiau, jei įmanoma, pasistenkite, kad kilpa būtų įtempta. Kai kurie žmonės mėgsta jas atlikti darbo dienos pradžioje arba pabaigoje, kaip “apšilimą” arba “atvėsimą”.

Atkreipkite dėmesį, kad šie raktiniai žodžiai įterpti taip, kad būtų išlaikytas teksto kontekstas ir nuoseklumas. Jei pageidaujate, kad jie būtų įrašyti konkrečiose vietose, maloniai prašome nurodyti.