Labākās prakses paraugprakse koda pārskatīšanā

Autors gūst labumu no cita skatījuma uz savu uzdevumu un kods. Viņi bieži apgūst jaunus trikus vai atklāj potenciāli optimālāku veidu, kā atrisināt kādu problēmu. Viņi arī droši izvietos savu izmaiņu kopumu, zinot, ka citi cilvēki ir pārbaudījuši koda pareizību un ir piekrituši, ka viss ir kārtībā.

Recenzents gūt labumu, redzot dažādas pieejas problēmu risināšanai darbībā. Viņi arī uzlabos savas prasmes kodu lasīšanā, kas ir ļoti svarīgi, kad viņi iedziļinās, piemēram, bibliotēkā, kas tiek novērtēta izmantošanai kādā projektā. projekts. Koda pārskatīšana ir arī iespēja mācīties gan autoram, gan pārskatītājam: iespējams, viņi arī apgūs jaunus trikus.

Portāls komanda kopumā, jo konkrētas problēmas risinājuma pārskatīšana prasa problēmas izpratni vismaz augstā abstrakcijas līmenī. Tas palīdz nojaukt nejaušus zināšanu silosus, kas var rasties team. Tas arī palielinās “autobusa faktoru”: tā kā vismaz divi cilvēki (vēlams vairāk) ir informēti par konkrētām izmaiņām, ir mazāka varbūtība, ka team neviens nezina, kā atjaunināt kādu moduli vai kāpēc varētu rasties kāda kļūda.

Klients ieguvumi no ātri un pārliecinoši ieviestām izmaiņām un risinājumiem. Kopā ar citām labākajām praksēm (piemēram, lielisku testu pārklājumu, CI/CD, sagatavošanas vidēm u. c.) koda pārskatīšana arī nodrošina, ka tas, kas tiek izvietots, ir drošs, saprātīgs un atbilst noteiktajām prasībām.

Šo vadlīniju nolūks un izmantošana

Lūdzu, atcerieties, ka šie ieteikumi galvenokārt ir paredzēti, lai radītu vidi, kas veicina vērienīgu un efektīvu problēmu risināšanu, vienlaikus radot drošības tīklu un veicinot uzticību un pārredzamību katram team dalībniekam.

Lai gan team ir ļoti ieteicams ievērot šīs vadlīnijas, tās nav paredzētas kā stingri un stingri noteikumi. Šī sistēma nav paredzēta arī kā “process”, kas precīzi jāievēro, jo stingri procesi parasti samazina ātrumu un veicina izšķērdību.

Jūs esat laipni aicināti balstīties uz šīm vadlīnijām savā team. Tomēr atcerieties, ka, mainoties team izstrādātājiem, viņi sagaidīs, ka koda pārskatīšana jebkurā team, kurā viņi pievienosies, joprojām balstīsies uz šo dokumentu. Saglabājiet visus papildu noteikumus, kas dokumentēti, un papildiniet šo dokumentu ar uzlabojumiem, kas ir ārkārtīgi labi darbojušies.

Pienākumi saistībā ar koda pārskatīšanu

Katram team dalībniekam ir noteikti pienākumi attiecībā uz koda pārskatīšanu. Turpmāk ir izklāstīti daži kodu pārskatīšanas "do un do't" un "ne", ņemot vērā lomu šajā procesā.

Projekta vadītājs

• DO nodrošināt, ka jūsu repozitoriji ir labi konfigurēti (piemēram, apvienošana ar jūsu ražošanas filiāli nav atļauta bez vismaz vienas apstiprinošas pārskatīšanas).
• DO nodrošināt, ka jūsu team saprot un piemēro šo praksi, un aktīvi strādāt, lai veicinātu izpratni par to, kāpēc mēs rīkojamies noteiktā veidā.
• DO pievērsiet uzmanību jebkurām neizšķirta situācijām, kurās nav iespējams atrisināt pretējus viedokļus: jūsu kā team tehniskā vadītāja pienākums ir šādos gadījumos izvēlēties piemērotāko risinājumu un nodrošināt darba virzību.
• Tomēr, NEDZĪVOJIET izmantot projekta vadību kā strupu instrumentu. NEDZĪVOJIET “pull rank”. DO atzinīgi vērtējiet savu risinājumu pārskatīšanu un kritiku tikpat lielā mērā, cik jūs to veicināt par ikviena cita cilvēka darbu.
• Apsveriet iespēju pievienot GitHub integrāciju savam team Slack kanālam. Tas var būt noderīgi, lai pārskatīšanas pieprasījumus labāk ievietotu recenzentu redzeslokā, taču atkarībā no kopējā apjoma jūsu kanālā tas var būt vai nebūt piemērots jūsu team.

Komandas loceklis

• Piedalieties koda pārskatīšanā. Nav pieņemami kodu nepārskatīt.
• PAMATI, lai veiktu koda pārskatīšanu: tavi teambiedri ir atkarīgi no tevis, lai panāktu progresu savā darbā!
• Ja noteikti nevarat veikt konkrētu pārskatu, DO skaidri un atklāti par to informēt.
• Tomēr, NEDZĪVOJIET pieņemt, ka jūs nevarat veikt noteiktu pārskatīšanu, jo nezināt šo sistēmas/darbības loģikas specifikāciju. Koda pārskatīšana ir svarīga mācību iespēja.
• Ja jums šķiet, ka nezināt pietiekami daudz par kādu tēmu, lai sagatavotu pārskatu, DO pajautājiet par to autoram: viņš labprāt paskaidros, kādām izmaiņām vajadzētu būt.
• NEDZĪVOJIET noliegt pārskatus, pamatojoties uz pieredzes līmeni (jūsu vai autora).
• DO mēģiniet pārskatīt vismaz tikpat daudz PR, cik sagatavojat. Vislabāk, ja jūsu pārskatīšanas attiecība pret nepieciešamo pārskatīšanu ir lielāka par 1 (jo īpaši lielākiem team).

Autors

• DO saprast, ka par sava koda pārskatīšanu esat atbildīgs jūs pats - jūsu team var aktīvi meklēt pull pieprasījumus pārskatīšanai, bet viņiem tas nav jādara.
• NEDZĪVOJIET vienmēr piešķiriet/pieprasiet pārskatus no tiem pašiem team dalībniekiem - jūs gūsiet lielāku labumu no daudzveidīga recenzentu loka (un, gluži pretēji, plašāks izstrādātāju loks gūs labumu no jūsu koda pārskatīšanas).
• NEDZĪVOJIET izslēgt kādu no pārskatīšanas, pamatojoties uz pieredzi. Jaunākie programmētāji gūst labumu no koda pārskatīšanas. Vecākie programmētāji gūst labumu no koda pārskatīšanas. Kā norādīts šī dokumenta ievadā, ikviens ieguvumi no koda pārskatīšanas.
• APSVERIET recenzentu atlasei izmantojiet nejaušības atlases rīku. Piemēram, programmā Rubīns, %w[teammate1 teammate2 teammate3].sample var radīt brīnumus.
• DO piešķiriet vismaz divus recenzentus saviem pull pieprasījumiem, ja vien tas nav absolūti neiespējami. Šādā veidā vairāk cilvēku gūs labumu no procesa (un ar trim cilvēkiem ir grūtāk panākt neizšķirtu rezultātu).
• DO būt atsaucīgam savos vilkšanas pieprasījumos. Lai gan jums nevajadzētu pārtraukt savu plūsmu, lai uzreiz atbildētu uz visiem komentāriem, pārliecinieties, ka jūsu atbildes ir savlaicīgas - pretējā gadījumā jūsu PR kavēsies koda pārskatīšanā bezgalīgi ilgi.
• DO paudiet atvērtu attieksmi. Vienmēr pieņemiet, ka recenzents cenšas palīdzēt ar vislabākajiem nodomiem. Paskaidrojiet savu loģiku, pievērsieties recenzenta argumentiem un atbildiet uz viņa jautājumiem.
• DO būt pieklājīgam. Nesaprašanās gadās, bet tām nav jāizkļūst ārpus kontroles un jākaitē atmosfērai team.
• DO esiet godīgi. Ja uzskatāt, ka šis ir labākais risinājums, pasakiet to un sniedziet savus argumentus. Ja esat pārliecināts, ka jūsu recenzenta priekšlikumi ir labāki par to, ko jūs sagatavojāt, pastāstiet to. Ja uzskatāt, ka var izveidot “labāko no abām pasaulēm” risinājumu, izmantojot gan jūsu, gan jūsu recenzenta idejas, ierosiniet to viņiem. Visbeidzot, strādājiet pie vienprātības savos vilkšanas pieprasījumos.
• DO atstājiet to komentāru atrisināšanu savam recenzentam - neatrisiniet tos tikai tāpēc, ka esat pārliecināts, ka viss ir kārtībā.
• DO aktīvi izskaidrojiet recenzentiem savu uzdevumu, pamatojumu un citas prasības. Ir labi nezināt - nav pieņemami noklusēt zināšanas.
• NEDZĪVOJIET domājat, ka zināt visu - mēs visi esam lieliski speciālisti, taču ir svarīgi, lai darbā ar jums būtu zināma pieticība.
• DO būt pirmais jūsu koda pārskatītājs. Uzvelciet recenzenta cepuri un rūpīgi skenējiet kodu, kā to darītu cilvēkam, kurš jums lielākoties nepatīk. Identificējiet un novērsiet visredzamākās lietas, piemēram, tukšās rindas, jebkādus atlikumus vai trūkstošās specifikācijas. Neizlaidiet neko - visticamāk, uz to tik un tā tiks norādīts. Netērējiet recenzentu laiku!
• DO rūpīgi aprakstiet savu pull pieprasījumu. Apraksts ir labs, ja, lasot kodu, recenzents nebūs pārsteigts par neko. Atcerieties, ka viņš nevar lasīt jūsu domas. Tāpēc ir svarīgi aprakstīt lietas, kas nav acīmredzamas, galvenos lēmumus ar pamatojumu vai visas jaunās klases un failus.
• APSVERIET izmantojot pull pieprasījuma veidni. Ja izmantojat Github, pievienojiet to savam repozitorijam zem .github/pull_request_template.md. Tā mudina visus team dalībniekus aprakstīt savus pull pieprasījumus. Ir arī daudz vieglāk rakstīt, ja apraksta lauks ir aizpildīts ar šablonu. Šeit jūs varat atrast veidni, ko mēs izmantojam vienā no mūsu projektiem. https://gist.github.com/weemanjz/a20ccb9f3f492b9bd21ab026a1d46353

Autors

• DO saprast, ka jūsu pienākums ir nodrošināt, lai jūsu koda pārskatīšana - jūsu team var aktīvi meklēt pull pieprasījumus pārskatīšanai, bet viņiem tas nav jādara.
• NEDZĪVOJIET vienmēr piešķirt/pieprasīt pārskatus no viena un tā paša kodu pārskatītāji - jūs gūsiet lielāku labumu no daudzveidīga recenzentu pulka (un, gluži otrādi, plašāks izstrādātāju loks gūs labumu no jūsu koda pārskatīšanas).
• NEDZĪVOJIET izslēgt kādu no pārskatīšanas, pamatojoties uz pieredzi. Jaunākie izstrādātāji gūst labumu no tā, ka veic koda pārskati. Vecākie izstrādātāji gūst labumu no koda pārskati. Kā norādīts šī dokumenta priekšvārdā, ikviens ieguvumi no darba veikšanas koda pārskati.

Recenzents

• DO izmantot ieteikumu, nevis prasību valodu. Tā vietā, lai teiktu “Jums vajadzētu uzlabot koda kvalitāti. tā vietā veicot X”, teiksim “Vai esat apsvērusi iespēju uzlabot koda kvalitāte darot X?”
• DO paskaidrojiet savus ieteikumus. “Es domāju, ka X ir labāk šeit, jo tas palīdz zināšanu nodošana un uzlabot koda kvalitāti.”
• Pat ja jūsu ieteikums ir saņemts no objektīviem avotiem (piem. koda stils vadlīnijas), DO lūgt autoram kaut ko darīt, nevis likt viņam kaut ko darīt. “Lūdzu, saglabājiet visus widgets frobnicated saskaņā ar mūsu koda stils ceļvedis - [saite]”
• NEDZĪVOJIET pieņemt, ka jūs visu zināt. “Es saprotu, ka šim logrīkam nekad nevajadzētu frobnicēt, un šajos apstākļos tas frobnicēs - vai tas ir izņēmums, kam nepieciešams izņēmums? koda pārskatīšana?”
• DO lietot iekļaujošu valodu. “Es uzskatu, ka mums nākotnē būtu labāk, ja mēs to šādi uzbūvētu. Ko jūs domājat par šo labāka koda pārskatīšana ieteikums?” un “Varbūt mums vajadzētu izmantot X šeit vietā, lai efektīva koda pārskatīšana?”
• DO nekavējoties veiciet savu koda pārskati. Jums nevajadzētu pārtraukt plūsmu, lai tos veiktu, bet, ja vien iespējams, mēģiniet noturēt cilpu saspringtu. Dažiem cilvēkiem patīk tās veikt darba dienas sākumā vai beigās kā “iesildīšanos” vai “atvēsināšanos”.

Lūdzu, ņemiet vērā, ka šie atslēgas vārdi ir ievietoti tā, lai saglabātu teksta kontekstu un saskaņotību. Ja vēlaties, lai tie tiktu ievietoti konkrētās vietās, lūdzu, norādiet.