Koodikontrolli parimad tavad

Autor kasu sellest, et nad saavad oma ülesandele teistsuguse vaatenurga ja kood. Nad õpivad sageli uusi nippe või avastavad potentsiaalselt optimaalsema viisi teatud probleemi lahendamiseks. Samuti võtavad nad oma muudatuste kogumi enesekindlalt kasutusele, teades, et teised inimesed on koodi korrektsust kontrollinud ja nõustunud, et kõik on korras.

Arvustaja saavad kasu sellest, et näevad erinevaid lähenemisviise probleemide lahendamisele praktikas. Samuti parandavad nad oma koodi lugemise oskust, mis on väga oluline, kui nad sukelduvad näiteks raamatukogu hindamisel kasutatavasse projekt. Koodi ülevaatus on ka õppimisvõimalus nii ülevaataja kui ka autori jaoks: nad võivad samuti õppida uusi nippe.

The meeskond tervikuna kasu, sest teatud probleemi lahenduse läbivaatamine eeldab probleemi mõistmist vähemalt kõrgel abstraktsioonitasemel. See aitab lõhkuda juhuslikke teadmussiilosid, mis võivad meeskonnas tekkida. Samuti suurendab see "bussifaktorit": kuna vähemalt kaks inimest (soovitavalt rohkem) on teadlikud mingist konkreetsest muudatusest, on väiksem tõenäosus, et keegi meeskonnas ei tea, kuidas moodulit uuendada või miks mingi kindel viga võib esineda.

Klient kasu kiiresti ja kindlalt rakendatud muudatustest ja lahendustest. Koos muude parimate tavadega (nagu suur testide katvus, CI/CD, staging-keskkonnad jne) tagavad ka koodikontrollid, et see, mida juurutatakse, on turvaline, mõistlik ja vastab nõuetele, nagu need on määratletud.

Käesolevate suuniste eesmärk ja kasutamine

Palun pidage meeles, et nende soovituste eesmärk on eelkõige luua keskkond, mis soodustab ambitsioonikat ja tõhusat probleemide lahendamist, luues samal ajal turvavõrgu ning edendades usaldust ja läbipaistvust iga meeskonnaliikme suhtes.

Kuigi on väga soovitatav, et meeskond järgiks neid suuniseid, ei ole need mõeldud kui ranged ja kindlad reeglid. See raamistik ei ole mõeldud ka "protsessina", mida tuleb täpselt järgida, sest jäigad protsessid kipuvad vähendama kiirust ja soodustavad raiskamist.

Olete rohkem kui teretulnud, kui kasutate neid suuniseid oma meeskonnas. Pidage siiski meeles, et kui arendajad vahetavad meeskondi, eeldavad nad, et koodikontrolli läbiviimine igas meeskonnas, millega nad liituvad, põhineb endiselt sellel dokumendil. Hoidke kõik täiendavad reeglid dokumenteeritud ja lisage sellesse dokumenti tagasi parandused, mis on erakordselt hästi toiminud.

Koodikontrolliga seotud kohustused

Igaühel meeskonnas on teatud kohustused seoses koodi läbivaatamisega. Järgnevalt on koodikontrolli teatud toimingud ja keelud sätestatud protsessi rollide kaupa.

Projektijuht

• DO veenduge, et teie repositooriumid on hästi konfigureeritud (näiteks ei ole lubatud ühinemised teie tootmisega seotud harusse ilma vähemalt ühe heakskiitva ülevaatuseta).
• DO tagage, et teie meeskond mõistab ja rakendab neid tavasid, ning töötage aktiivselt selle nimel, et edendada arusaamist, miks me teeme asju teatud viisil.
• DO jälgige, kas tekib olukordi, kus vastandlikke arvamusi ei ole võimalik lahendada: teie kui oma meeskonna tehnilise juhi ülesanne on sellistel juhtudel valida asjakohasem lahendus ja hoida töö edenemist.
• Siiski, ÄRGE kasutada projektijuhtimist tümpsuvahendina. ÄRGE "tõmmake auastet". DO tervitage oma lahenduste ülevaatamist ja kriitikat sama palju, kui julgustate neid kellegi tööde kohta.
• KASUTAGE GitHubi integratsiooni lisamist oma meeskonna Slacki kanalile. See võib olla kasulik, et panna ülevaatustaotlused paremini ülevaatajate tähelepanu alla, kuid sõltuvalt teie kanali üldisest mahust võib see teie meeskonnale sobida või mitte.

Meeskonna liige

• Osalege koodide ülevaatustes. On vastuvõetamatu jätta kood läbi vaatamata.
• ÄRGE unustage teha oma koodi ülevaatusi: teie meeskonnakaaslased sõltuvad teiest, et nende töö edeneks!
• Kui te absoluutselt ei saa teatud ülevaadet teha, DO edastage seda selgelt ja avalikult.
• Siiski, ÄRGE eeldada, et te ei saa teha teatavat ülevaatust, sest te ei tunne seda moodulit/ süsteemi/äriloogika spetsifikaati. Koodi ülevaatus on oluline õppimisvõimalus.
• Kui tunnete, et te ei tea millestki piisavalt, et teha ülevaade, DO küsige selle kohta autorilt: ta selgitab hea meelega, mida muudatused peaksid tegema.
• ÄRGE keelduda hinnangute andmisest kogemuste taseme alusel (teie või autori).
• DO püüdke vaadata läbi vähemalt sama palju PR-töid, kui te toodate. Ideaalis peaksite hoidma oma ülevaatuste arvu üle 1 (eriti suuremate meeskondade puhul).

Autor

• DO mõistke, et teie vastutus on teie koodi ülevaatamine - teie meeskond võib proaktiivselt otsida ülevaatamiseks vajalikke tõmbepäringuid, kuid nad ei pea seda tegema.
• ÄRGE määrake/nõuda ülevaatusi alati samadelt meeskonnaliikmetelt - te saate rohkem kasu mitmekülgsest ülevaatajaskonnast (ja vastupidi, teie koodi ülevaatamisest saab kasu suurem hulk arendajaid).
• ÄRGE jätta keegi kogemuse põhjal ülevaatusest välja. Nooremad arendajad saavad koodi läbivaatamisest kasu. Vanemad arendajad saavad koodi läbivaatamisest kasu. Nagu on märgitud käesoleva dokumendi eessõnas, kõik kasu koodide läbivaatamisest.
• KASUTAGE kasutades arvustajate valimiseks juhuslikkuse määraja. Näiteks Ruby's, %w[meeskonnakaaslane1 meeskonnakaaslane2 meeskonnakaaslane3].sample võib teha imet.
• DO määrake vähemalt kaks retsensenti oma tõmbetaotlustele, välja arvatud juhul, kui see on täiesti võimatu. Nii saavad protsessist rohkem inimesi kasu (ja kolme inimesega on raskem jõuda võrdsele tulemusele).
• DO olge oma tõmbepäringutes vastutulelik. Kuigi te ei tohiks katkestada oma töövoolu, et vastata kohe praegu kõikidele kommentaaridele, veenduge, et teie vastused on õigeaegsed - vastasel juhul jäävad teie PR-id koodikontrollile määramata ajaks.
• DO tuua avatud suhtumine. Eeldage alati, et teie ülevaataja püüab aidata parimate kavatsustega. Selgitage oma loogikat, pöörduge retsensendi argumentide poole ja vastake tema küsimustele.
• DO olla viisakas. Arusaamatusi juhtub, kuid need ei pea väljuma kontrolli alt ja kahjustama meeskonna õhkkonda.
• DO ole aus. Kui te usute, et see on parim lahendus, siis öelge seda ja esitage oma argumendid. Kui olete veendunud, et teie retsensendi ettepanekud on paremad kui see, mille te välja pakkusite, siis öelge seda neile. Kui te arvate, et nii teie kui ka teie retsensendi ideid kasutades on võimalik luua "parim lahendus mõlemast maailmast", siis tehke neile ettepanek. Lõppkokkuvõttes töötage oma pull-päringutes konsensuse saavutamise nimel.
• DO jätke nende märkuste lahendamine oma ülevaatajale - ärge lahendage neid lihtsalt sellepärast, et olete veendunud, et nüüd on kõik korras.
• DO selgitage aktiivselt oma ülesannet, põhjendusi ja muid nõudeid oma hindajatele. On okei, kui te ei tea - teadmiste varjamine ei ole vastuvõetav.
• ÄRGE eeldada, et te teate kõike - me kõik oleme suurepärased spetsialistid, kuid on oluline, et te võtaksite tööle kaasa teatava alandlikkuse.
• DO olla teie koodi esimene ülevaataja. Kandke retsensendi mütsi ja skaneerige koodi hoolikalt, nagu te teeksite selle inimese puhul, kes teile enamasti ei meeldi. Tuvastage ja kõrvaldage kõige ilmsemad asjad, nagu tühjad read, mis tahes ülejäägid või puuduvad spetsifikatsioonid. Ärge jätke midagi vahele - tõenäoliselt osutatakse sellele niikuinii. Ärge raiskage retsensendi aega!
• DO kirjeldage põhjalikult oma tõmbetaotlust. Kirjeldus on hea, kui ülevaataja ei üllata midagi koodi lugedes. Pidage meeles, et ta ei saa lugeda teie mõtteid. Seepärast on oluline kirjeldada asju, mis ei ole ilmselged, võtmeotsuseid koos põhjendusega või kõiki uusi klasse ja faile.
• KASUTAGE kasutades tõmbetaotluse malli. Kui kasutate Githubi, lisage see oma repositooriumi aadressil .github/pull_request_template.md. See julgustab kõiki meeskonnaliikmeid kirjeldama oma tõmbetaotlusi. Samuti on palju lihtsam kirjutada, kui teil on kirjeldus väli täidetud malliga. Siit leiate malli, mida me kasutame ühes oma projektis https://gist.github.com/weemanjz/a20ccb9f3f492b9bd21ab026a1d46353

Autor

• DO mõista, et teie kohustus on oma koodi läbivaatamine - teie meeskond võib proaktiivselt otsida läbivaadatavaid tõmbetaotlusi, kuid nad ei pea seda tegema.
• ÄRGE alati määrata/nõuda ülevaatusi samalt asutuselt. koodikontrollijad - saate rohkem kasu mitmekülgsest arvustajate hulgast (ja vastupidi, teie koodi arvustamisest saab kasu suurem hulk arendajaid).
• ÄRGE jätta keegi kogemuse põhjal ülevaatusest välja. Nooremad arendajad saavad kasu koodide ülevaated. Vanemad arendajad saavad kasu koodide ülevaated. Nagu on märgitud käesoleva dokumendi eessõnas, kõik kasu tulemuslikkusest koodide ülevaated.

Arvustaja

• DO kasutage nõuete asemel soovituste keelt. Selle asemel, et öelda "Sa peaksid parandada koodi kvaliteeti tehes hoopis X", ütleme "Kas te olete kaalunud parandada koodi kvaliteet tehes X?"
• DO selgitage oma ettepanekuid. "Ma arvan, et X on siin parem, sest see aitab teadmiste edasiandmine ja koodi kvaliteedi parandamine."
• Isegi kui teie soovitus pärineb objektiivsetest allikatest (nt. koodistiil suunised), DO paluda autoril midagi teha, selle asemel et talle midagi öelda. "Palun hoidke kõik vidinad frobnicated vastavalt meie koodistiil juhend - [link]"
• ÄRGE eeldada, et te teate kõike. "Minu arusaamise järgi ei tohiks see vidin kunagi frobnitseda ja sellistel tingimustel see teebki - kas see on erand, mis vajab koodi läbivaatamine?"
• DO kasutada kaasavat keelt. "Ma usun, et meil oleks tulevikus parem, kui me ehitaksime selle niimoodi. Mida te arvate sellest koodide parem läbivaatamine ettepanek?" ja "Võib-olla peaksime kasutama siin hoopis X-i. tõhus koodikontroll?"
• DO olema kiire oma koodide ülevaated. Te ei tohiks nende tegemiseks oma voolu katkestada, kuid püüdke võimalusel hoida silmus tihedana. Mõnele meeldib neid teha kas tööpäeva alguses või lõpus, kas "soojendusena" või "jahutusena".

Pange tähele, et need märksõnad on lisatud nii, et teksti kontekst ja sidusus säiliksid. Kui soovite, et need oleksid mõnes konkreetses kohas, siis palun täpsustage.