Bestu vinnubrögð við kóðaskoðun

Höfundurinn nýtur góðs af því að fá aðra sýn á verkefni sitt og kóði. Þeir læra oft nýjar aðferðir eða uppgötva mögulega betri leið til að leysa ákveðið vandamál. Þeir munu einnig innleiða breytingasettið sitt af sjálfstrausti, vitandi að aðrir hafa athugað kóðann til að ganga úr skugga um réttmæti hans og samþykkt að allt sé í lagi.

Umsagnaraðilinn Þeir njóta góðs af því að sjá mismunandi nálganir við lausn vandamála í framkvæmd. Þeir munu einnig bæta færni sína í að lesa kóða, sem er mjög mikilvægt þegar kafað er til dæmis í bókasafn sem er metið til notkunar í verkefni. Kóðaskoðun er jafnframt lærdómsfæri fyrir skoðandann sem fyrir höfundinn: þeir geta vel lært nýjar aðferðir.

Þeir lið sem heild hefur ávinning þar sem endurskoðun lausnar á ákveðnu vandamáli krefst þess að skilja vandamálið að minnsta kosti á háu abstraktstigi. Þetta hjálpar til við að rífa niður óvart myndaða þekkingarsíló sem kunna að myndast í team. Það eykur einnig “bus factor”: þar sem að minnsta kosti tveir einstaklingar (helst fleiri) eru meðvitaðir um tiltekna breytingu, er minni líkur á að enginn í team viti hvernig á að uppfæra eininguna eða af hverju ákveðinn bugur gæti verið að koma upp.

Viðskiptavinurinn Nýtur góðs af því að breytingar og lausnir séu innleiddar hratt og af fullri vissu. Saman með öðrum bestu starfsháttum (svo sem frábærri prófunarþekju, CI/CD, undirbúningsumhverfi o.s.frv.) tryggja kóðaskoðanir einnig að það sem innleitt er sé öruggt, skynsamlegt og uppfylli tilgreindar kröfur.

Tilgangur og notkun þessara leiðbeininga

Vinsamlegast munið að umfram allt er ætlunin með þessar tillögur að skapa umhverfi sem hvetur til metnaðarfullrar og skilvirkrar lausnar vandamála, á sama tíma og það myndar öryggisnet og eflir sjálfstraust og gagnsæi hjá hverjum team-meðlimi.

Þó að mjög eindregið sé mælt með því að team fylgi þessum leiðbeiningum, eru þær ekki ætlaðar sem harðar og óbreytanlegar reglur. Þessi rammi er heldur ekki ætlaður sem “ferli” sem skuli fylgt nákvæmlega, þar sem stíf ferli hafa tilhneigingu til að draga úr hraða og stuðla að sóun.

Þú ert meira en velkominn til að byggja ofan á þessar leiðbeiningar innan team-verkefnisins þíns. Mundu þó að þegar forritarar færa sig á milli team-verkefna munu þeir gera ráð fyrir að kóðaskoðun í hvaða team-verkefni sem þeir ganga til liðs við sé enn byggð á þessu skjali. Halda skráðum öllum viðbótarreglum og leggja fram tillögur um umbætur sem hafa reynst einstaklega vel í þessu skjali.

Ábyrgð varðandi kóðaskoðun

Allir á team bera ákveðnar ábyrgðir varðandi kóðaskoðun. Hér að neðan eru tilgreind nokkur atriði sem ber að gera og forðast við kóðaskoðun eftir hlutverki í ferlinu.

Verkefnisstjóri

• Gerðu Tryggið að geymslur ykkar séu vel stilltar (t.d. eru samrunnar inn á framleiðslugrein ekki leyfðar án að minnsta kosti eins samþykkis í yfirferð).
• Gerðu Tryggðu að team þitt skilji og beiti þessum vinnubrögðum og vinni virkt að því að efla skilning á því hvers vegna við gerum hlutina á ákveðinn hátt.
• Gerðu Vertu á varðbergi gagnvart öllum jafnteflum þar sem andstæðar skoðanir ekki er hægt að leysa: sem tæknileiðtogi fyrir team-ið þitt ber þér ábyrgð að velja viðeigandi lausn í slíkum tilvikum og halda vinnunni áfram.
• Hins vegar, Ekki Notaðu verkefnisstjórn sem daufan hamar. Ekki “Nota stöðustig. Gerðu Velkomin er yfirferð og gagnrýni á lausnir þínar, rétt eins og þú hvetur aðra til að gera slíkt við vinnu annarra.
• Íhugaðu að bæta GitHub-samþættingu við Slack-rás team þíns. Það gæti hjálpað til við að koma beiðnum um yfirferð betur á ratsjá yfirskoðenda, en allt eftir heildarmagni í rásinni þinni gæti þetta hentað eða ekki hentað team þínum.

Liðsmaður

• Taktu þátt í kóðaskoðunum. Það er óásættanlegt að skoða ekki kóðann.
• Mundu að gera kóðaskoðanir þínar: teamfélagar þínir treysta á þig til að komast áfram með vinnu sína!
• Ef þú getur algjörlega ekki gert ákveðna yfirferð, Gerðu miðla því skýrt og opinskátt.
• Hins vegar, Ekki Gerðu ráð fyrir að þú getir ekki gert ákveðna yfirferð vegna þess að þú þekkir ekki þann hluta, hlið kerfisins eða viðskiptalógíkurinnar. Kóðayfirferð er mikilvæg lærdómsupplifun.
• Ef þér finnst þú ekki vita nóg um eitthvað til að skrifa umsögn, Gerðu Spyrðu höfundinn um það: hann mun fúslega útskýra hvað breytingarnar eiga að gera.
• Ekki Neita umsögnum byggðum á reynslustigi (yours eða höfundarins).
• Gerðu Reyndu að fara yfir að minnsta kosti jafn margar PR-tilkynningar og þú sendir inn. Helst ættir þú að halda hlutfalli yfirferða sem þú gefur og krafðra yfirferða yfir 1 (sérstaklega á stærri team-um).

Höfundur

• Gerðu skilja að það er þín ábyrgð að láta kóðann þinn fara yfir – team þinn gæti virkt leitað að pull-beiðnum til að fara yfir, en þeir þurfa það ekki.
• Ekki Ætlaðu/beiððu alltaf um endurskoðanir frá sömu team-meðlimum – þú munt hagnast meira á fjölbreyttum hópi endurskoðenda (og öfugt, fjölbreyttari hópur forritara mun hagnast á því að endurskoða kóðann þinn)
• Ekki útiloka einhvern frá yfirferð byggt á reynslu. Ungir forritarar hafa gagn af kóðayfirferð. Reynslumiklir forritarar hafa gagn af kóðayfirferð. Eins og fram kemur í formála þessa skjals, all people Ávinningur af yfirferð kóða.
• Íhugaðu að nota slembitölvu til að velja umsagnara þína. T.d. í Rúbín, %w[teammate1 teammate2 teammate3].sýnishorn getur unnið kraftaverk.
• Gerðu Úthlutaðu að minnsta kosti tveimur umsagnaraðilum í pull-beiðnirnar þínar, nema það sé algjörlega ómögulegt. Þannig hagnast fleiri á ferlinu (og með þremur manns er erfiðara að enda á jafntefli).
• Gerðu Vertu viðbragðsfljótur í pull-beiðnum þínum. Þó að þú eigir ekki að rjúfa vinnuflæði þitt til að svara strax öllum athugasemdum, vertu viss um að svörin þín berist tímanlega – annars munu pull-beiðnir þínar hanga í kóðaskoðun óákveðið.
• Gerðu Vertu með opinn hug. Gefðu þér alltaf að umsagnaraðilinn sé að reyna að hjálpa með allar bestu fyrirætlanir. Útskýrðu rökstuðning þinn, taktu á rökum umsagnaraðilans og svaraðu spurningum þeirra.
• Gerðu Vertu kurteis. Misskilningar gerast, en þeir þurfa ekki að fara úr böndunum og skemma andrúmsloftið í team.
• Gerðu Vertu heiðarlegur. Ef þú telur að þetta sé besta lausnin, segðu það og leggðu fram rök þín. Ef þú sannfærist um að tillögur endurskoðandans séu betri en það sem þú framleiddir, segðu þeim það. Ef þú telur að hægt sé að búa til lausn sem sameinar það besta úr þínum og endurskoðandans hugmyndum, leggðu hana fram fyrir þá. Að lokum skaltu vinna að samkomulagi í pull-beiðnum þínum.
• Gerðu Láttu endurskoðandann þinn sjá um að leysa athugasemdir þeirra – ekki bara leysa þær af því að þú ert sannfærður um að allt sé í lagi núna.
• Gerðu Útskýrðu verkefni þitt, rökstuðning þinn og aðrar kröfur fyrir endurskoðendum þínum af kostgæfni. Það er í lagi að vita ekki – en það er ekki ásættanlegt að halda þekkingu fyrir sig.
• Ekki Gerðu ráð fyrir að þú vitir allt – við erum öll frábær sérfræðingar, en það er mikilvægt að koma með ákveðna auðmýkt með sér til vinnu.
• Gerðu Vertu fyrsti endurskoðandi kóðans þíns. Taktu á þig hlutverk endurskoðanda og skoðaðu kóðann vandlega eins og þú myndir gera fyrir þann sem þér mislíkar mest. Finndu og fjarlægðu augljósustu atriðin, eins og tómar línur, afganga eða vantar skilgreiningar. Ekki sleppa neinu – það mun líklega verða bent á það engu að síður. Eyððu ekki tíma endurskoðenda!
• Gerðu Lýstu pull-beiðni þinni gaumgæfilega. Lýsingin er góð þegar yfirlesarinn verður ekki hissa á neinu þegar hann les kóðann. Mundu að hann getur ekki lesið hugsanir þínar. Þess vegna er mikilvægt að lýsa hlutum sem eru ekki augljósir, lykilákvörðunum með ástæðu þeirra og öllum nýjum flokkum og skrám.
• Íhugaðu með því að nota pull request-sniðmát. Ef þú notar Github, bættu því við í gagngeymsluna þína undir .github/pull_request_template.md. Það hvetur alla team-meðlimi til að lýsa pull-beiðnum sínum. Það er líka mun auðveldara að skrifa þegar lýsingarreiturinn er fylltur út með sniðmáti. Hér finnur þú sniðmát sem við notum í einu af verkefnum okkar. https://gist.github.com/weemanjz/a20ccb9f3f492b9bd21ab026a1d46353

Höfundur

• Gerðu skilja að það er þín ábyrgð að hafa þitt kóðaskoðun – team þinn getur virkt leitað að pull-beiðnum til að fara yfir, en það þarf ekki.
• Ekki Ætla/beiða alltaf um umsagnir frá sama kóðaskoðendur – þú munt hafa meiri hag af fjölbreyttum hópi yfirlesara (og öfugt, mun fjölbreyttari hópur forritara hafa hag af því að yfirlesa kóðann þinn)
• Ekki Útlokar einhvern úr endurskoðun á grundvelli reynslu. Junior forritarar njóta góðs af því að framkvæma Kóðaskoðanir. Yngri forritarar njóta góðs af frammistöðu Kóðaskoðanir. Eins og fram kemur í formála þessa skjals, all people Ávinningur af frammistöðu Kóðaskoðanir.

Umsagnaraðili

• Gerðu Notaðu orðróma sem gefa í skyn í stað krafna. Í stað þess að segja “Þú ættir bæta gæði kóðans með því að gera X í staðinn”, segja “Hefurðu íhugað að bæta? gæði kóða með því að gera X?”
• Gerðu Útskýrðu tillögur þínar. “Ég held að X sé betra hér vegna þess að það hjálpar við þekkingarflutningur og að bæta gæði kóðans.”
• Jafnvel þó tillaga þín komi frá hlutlausum heimildum (t.d. kóðastíll leiðbeiningar), Gerðu Biððu höfundinn um að gera eitthvað í stað þess að segja honum að gera eitthvað. “Vinsamlegast haldið öllum vígötum frobníkuðum samkvæmt okkar kóðastíll leiðbeiningar – [hlekkur]”
• Ekki Gerðu ráð fyrir að þú vitir allt. “Samkvæmt skilningi mínum ætti þessi viðbót aldrei að frobnicate, og við þessar aðstæður mun hún gera það – er þetta undantekning sem þarf a kóðaskoðun?”
• Gerðu Notaðu innifalið málfar. “Ég tel að okkur myndi ganga betur í framtíðinni ef við byggðum þetta svona. Hvað finnst þér um þetta? betri kóðaskoðun Tillaga?” og “Kannski ættum við að nota X hér í staðinn fyrir a Árangursrík kóðaskoðun?”
• Gerðu Vertu fljót(ur) að gera þitt Kóðaskoðanir. Þú ættir ekki að rjúfa flæðið þitt til að gera þau, heldur reyna að halda hringnum þröngum ef mögulegt er. Sumir kjósa að gera þau annaðhvort í byrjun eða í lok vinnudagsins, sem upphitun eða niðurlag.

Vinsamlegast athugið að þessum lykilorðum hefur verið komið fyrir á þann hátt að samhengi og samheldni texta haldist óskert. Ef þið viljið hafa þau á ákveðnum stöðum, vinsamlegast tilgreinið.