Kaip pateikti pull request, kad kodo peržiūra būtų efektyvesnė ir greitesnė?

Kaip pateikti kodą peržiūrai

About The Author

Šarūnas is a front-end programmer. He loves programming with JavaScript and it is not only a part of work, but also a hobby. Currently, Šarūnas is successfully programming in the PlusPort project using React technology.

Pagal Agile metodologiją dirbančių komandų greitis matuojamas po kiekvieno sprinto. Vertinant komandos rezultatus galima pastebėti, jog kiekvieno komandos nario įpročiai gali sukelti drugio efektą . Net ir maži pakitimai komandos narių elgsenoje turi įtakos galutiniam rezultatui, todėl svarbu susikurti nuolatinę rutiną paremtą gerais įpročiais.

Pull request’ų svarba

Vienas iš  rekomenduojamų įpročių – nuolatinės kodo peržiūros  (code review). Bet tam, kad jos būtų efektyvios svarbu ne tik užtikrinti gerą kodo peržiūros procesą, bet ir skirti dėmesio kaip kodą pateikiame. Gali kilti klausimas: kodėl reikia rūpintis pull request’o kokybe? Juk turėtų rūpėti tik kodo kokybė! Kad tokių klaidingų klausimų nekiltų, šiame blog’o, įraše aptarsime, kodėl svarbus taisyklingas kodo pateikimo procesas.

„Gali kilti klausimas: kodėl reikia rūpintis pull request’o kokybe? Juk turėtų rūpėti tik kodo kokybė!“

Programuotojo darbas nėra tik kodo rašymas, todėl ir darbo kokybė neturėtų apsiriboti kodu. Norint mokytis, reikia eksperimentuoti ir išbandyti naujus metodus. Tačiau nuolat eksperimentuojant, be abejonės, susiduriama ir su neteisingais sprendimais. Tai ir yra natūralus mokymosi procesas, kurio metu nesėkmės yra paverčiamos naudingomis pamokomis. Tad išmokus aiškiai pateikti savo kodą išlošime – vertintojui bus lengviau komentuoti, pastebėti klaidingus sprendimus ir duoti naudingus pasiūlymus, o  kodo autoriui, bus lengviau tobulėti ir mokytis.

Kodėl teiginys, kad pull request’ai lėtina produkto kūrimą yra neteisingas?

Tokia formuluotė gali pasirodyti teisinga tik tada, jeigu komandoje pull request’ai nėra vertinami ir jų peržiūra yra lėta ir neproduktyvi. Iš tiesų, tokiu atveju reikėtų pergalvoti pačios peržiūros procesą, reikėtų suprasti, kodėl jis stringa ir kaip jį paspartinti. Būtent tai ir esame aptarę savo elektroninėje knygoje: Įžvalgos apie kokybišką Code Review. 

Kita vertus, komandoje reikėtų suprasti švaraus kodo svarbą ir dažniau peržiūrėti vienas kito rašomą kodą. Naudojantis šia praktika kodas neužsistovi ir programuotojai susikuria aplinką, kurioje yra išgirstamos įvairios nuomonės ir turimos nuolatinės žinių dalijimosi sesijos. 

„Komandoje reikėtų suprasti švaraus kodo svarbą ir dažniau peržiūrėti vienas kito rašomą kodą.“

Kaip paruošti kodą peržiūrai (code review)?

Labai svarbu turėti supratimą ir konkrečius žingsnius kaip paruošti kodą peržiūrai, kad darbas vyktų efektyviai ir sklandžiai. 

Štai keli Visma Lietuva programuotojų naudojami patarimai kaip efektyvinti kodo peržiūros procesą:

  • Prieš atiduodant kodą vertintojui kodas turi būti peržiūrėtas paties autoriaus.
  • Pull request’as turėtų būti pateiktas aiškiai – reikia pažymėti WIP (work in progress), kad vertintojui būtų lengva suprasti paruoštą kodą. Taip pat ir kodo autoriui bus lengviau pastebėti savo klaidas, jeigu prie kodo bus papildomai padirbėta. 

Pull request aprašymasPavyzdys, kur pateikti pull request’ą GitHub’e

  • Turėtų būti aprašymas įvedantis į kontekstą – sutaupo laiko vertintojui, nes nereikia ieškoti ir suprasti, kam skirtas kodas.
  • Jeigu yra galimybė logikos pakeitimai turi būti atskirti nuo formatavimo.
  • Atitinkama kodo apimtis – peržiūrimo kodo optimalus dydis 200 eilučių. Maksimalus 400 – ilgesnis kodas vertintojo nebus peržiūrimas taip nuodugniai. Tą matome ir grafike pateiktame pagal Cisco Systems atliktą Code Review studiją. Defektų tankis dramatiškai sumažėja, kai tikrinimo eilučių skaičius viršija 200, o po 400 – beveik lygus nuliui.

Analizė pagal CiscoAnalizė atlikta pagal Cisco Code Review studiją. 

Naudojantis šiais patarimais dingsta priežastys, kodėl komandos kartais priešinasi pull request’ams ir neatlikinėja kodo peržiūrų. Svarbiausia naudotis patogia struktūra ir nedaryti didelių pakeitimų rutinoje.

Kaip turi atrodyti pull request’o šablonas?

Komandoje turėtų būti sukurtas patogus pull request’o šablonas. Sukurtas šablonas gali būti patalpintas pull_request_template.md faile. Tai leis standartizuoti kodo aprašymą ir vertintojui bus nesunku suprasti pakeitimo mastą ir kontekstą. Šablonu rekomenduojama apimti šiuos punktus:

  • Pull request’o pavadinime turėtų būti užduoties numeris (task ID)
  • Nuoroda į užduotį (ne visada būtina, jei nurodytas task ID)
  • Pakeitimo aprašymas
  • Pakeitimo tipas (naujas funkcionalumas, klaidos taisymas, nesuderinami pakeitimai ir t.t.)
  • Sąrašas, kuriuo nusakomi autoriaus atlikti veiksmai ir ar kodas atitinka nustatytas taisykles
  • Jeigu projektas yra biblioteka, turėtų būti sąrašas su būtinais atlikti žingsiniais (pakelta versija, atnaujintas CHANGELOG ir t.t.).
  • Jeigu kodas turėjo pakeitimų susijusių su UI – pridėti pakeitimo ekrano kopijų.

Galite naudotis mano naudojamu šablono pavyzdžiu:

Pull request pavyzdys

Pull request’o šablono pavyzdys

Išvados

Šabloną galima koreguoti pritaikant prie savo komandos darbo proceso. Jei naudojamas užduočių valdymo įrankis, kai kurie punktai gali dubliuotis ir būti nereikalingi. Svarbiausia susikurti šabloną, kuris būtų visai komandai priimtinas, vienodas ir aiškus. Taip kodo autorius nepamirš užpildyti reikalingos informacijos, o vertintojas ras jam aktualią informaciją.

Nei viena komanda neturėtų nuvertinti pull request’ų svarbos, tai turėtų tapti komandos privalumu. Tai ne tik pagerins komandos žinių dalijimąsi, bet pakels ir vertintojų motyvaciją peržiūrėti kodą, o svarbiausia – pakels visos komandos efektyvumo lygį. 

„Nei viena komanda neturėtų nuvertinti pull request’o svarbos, tai turėtų tapti komandos privalumu.“

Rekomenduoju

Šiame blog’o įraše kalbėjau apie tai kaip pateikti savo kodą vertintojui, kad peržiūros būtų efektyvesnės ir greitesnės. Norint kelti kompetenciją ir produkto kokybę reguliariai atlikti kodo peržiūras ne tik rekomenduotina, bet ir būtina. Tad, jeigu įdomus visas procesas, naudojami įrankiai ir dažniausiai pasitaikančios klaidos peržiūros procese, tai rekomenduoju atsisiųsti naujausią, mano kolegų parašytą, elektroninę knygą: Įžvalgos apie kokybišką Code Review. Laikas tikrai neprailgs, nes knygoje sudėta susiteminta daugelio metų patirtis ir naudingi patarimai.

Elektroninė knyga apie kodo peržiūras

7