Pull request'ų svarba
Vienas iš rekomenduojamų įpročių – nuolatinės kodo peržiūros (code review). Norint, kad jos būtų efektyvios, svarbu ne tik užtikrinti gerą kodo peržiūros procesą, bet ir skirti dėmesio kodo pateikimui. Gali kilti klausimas: kodėl reikia rūpintis pull request’o kokybe? Juk turėtų rūpėti tik kodo kokybė! Tam, 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.
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 ne tik išgirstamos įvairios nuomonės, bet ir organizuojamos 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 twoday 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.
Pavyzdys, kur pateikti pull request’ą GitHub’e
-
Reikalingas 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ė atlikta pagal Cisco Code Review studiją.
Naudojantis šiais patarimais dingsta priežastys, kodėl komandos kartais priešinasi pull request’ams ir neatlieka 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 žemiau pateiktu šablono pvz.:
Pull request’o šablono pvz.
Išvados
Šabloną galima koreguoti pritaikant prie savo komandos darbo proceso. Jeigu naudojamas užduočių valdymo įrankis, kai kurie punktai gali dubliuotis ir tapti 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ą.
Nė 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į.