Koodin katselmointi vertaisryhmittäin

Kurssilla hyödynnämme demojen lisäksi koodikatselmointeja vertaispalautteen saamiseksi.

Katselmoitte kurssilla itse vertaisryhmänne koodia ja saatte vastavuoroisesti vertaisryhmältänne palautetta omasta koodistanne. Samalla opimme katselmoimaan koodia ja antamaan rakentavaa palautetta sekä kehitysehdotuksia.

Katselmoinnit suoritetaan siten, että kukin ryhmä tekee GitHub-repositorioonsa issuen otsikolla “Katselmointipyyntö”. Vertaisryhmä antaa palautteen issueseen kommentin muodossa.

Alkuvaiheessa koodin tai katselmointien laadun ei tarvitse olla häikäisevää, vaan päätavoite on kehittyä kurssin aikana.

TL;DR: tärkeimmät actionpointit

1. Tehkää katselmointipyyntö vertaisryhmällenne luomalla GitHub repositorioonne issue, jonka otsikko on “Katselmointipyyntö”.
2. Katselmointipyynnössä tulee eritellä noin 100-200 riviä, josta haluatte saada palautetta. Mainitkaa pyynnössä katselmoitavat tiedostostot ja tarpeen tullen niiden osat (esim. tietyt metodit luokasta).
3. Kertokaa katselmointipyynnössänne lyhyesti, miten valitsemanne koodin laatu on varmistettu. Voitte esimerkiksi laittaa linkin automatisoituihin testeihin tai kuvailla muuten millä tavoin olette varmistaneet koodin toimivuuden.
4. Vertaisryhmä lukee katselmointipyynnön avamaalla “Katselmointipyyntö”-issuen repositorion “Issues”-tabilta, katselmoi koodin ja kirjoittaa katselmointipalautteen issueseen kommenttina. Kommentin voi kirjoittaa lomakkeella issuen alaosassa.
5. Kun katselmointipalaute on kirjoitettu, issuen kommenteissa voi käydä katselmoinnista vapaamuotoista keskustelua.

Käytännöt

Koodin katselmoimiseksi ryhmän ei tarvitse kloonata itselleen toisen ryhmän koodia eikä suorittaa sitä. Tällä vältetään monimutkaiset ympäristöjen pystyttämiset ja riippuvuuksien asentamiset, jotka vievät aikaa varsinaiselta katselmoinnilta ja kehitysehdotuksilta. Ohjelman testaamisen sijaan keskitytte siis lukemaan koodia ja arvioimaan sen selkeyttä ja luettavuutta.

Selkeän, luettavan ja ylläpidettävän koodin kehittämisestä on julkaistu mm. laajaan suosioon noussut Clean Code -kirja. Kirjan lainaaminen ja sen lukeminen kokonaan ei ole välttämätöntä, mutta suosittelemme lukemaan esimerkiksi kirjan tiivistelmän tai samasta kirjasta erityisesti JavaScriptiä varten sovelletun tyylioppaan.

Arvioikaa katselmointipyynnössä saamaanne kuvausta vertaisryhmän laadunvarmistuskäytännöistä. Oletteko luottavaisia tehtyyn laadunvarmistukseen, tai onko teillä kehitysehdotuksia esimerkiksi manuaalisen tai automatisoidun testauksen suhteen?

Antamanne palautteen ei tarvitse välttämättä pohjautua annettuihin lähteisiin, vaan voitte hyvin kirjoittaa omin sanoin kokemuksestanne annetun koodin lukemisessa.

Projektin valmistelu katselmoitavaksi

Osa projekteista koostuu useista eri osista, kuten front-endistä ja back-endistä. Projekteissa on myös merkittäviä osia valmiista tutoriaaleista tai malliprojekteista lainattuja osia, joiden katselmointi ei ole ryhmän kehittymisen kannalta kovin hyödyllistä. Siksi jokaisen ryhmän on rajattava omasta projektista “kourallinen” koodia, eli suuruusluokkaa 1-2 tiedostoa tai 100-200 riviä, joista toivotte eniten saavanne palautetta.

Lisätkää katselmointipyyntöön linkki koodeihinne sekä selkeästi eriteltynä ne tiedostot, luokat, funktiot tai muut yksiköt joista toivotte palautetta. Kertokaa katselmointipyynnössänne myös lyhyesti, miten valitsemanne koodin laatu on varmistettu. Voitte esimerkiksi laittaa linkin automatisoituihin testeihin tai kuvailla muuten millä tavoin olette varmistaneet katselmoitavan koodin toimivuuden.

Voitte koodin ohessa pyytää myös palautetta dokumentaatiostanne tai ohjeistanne. Tarvittaessa antakaa lisäohjeet, kuten mistä branchista haluatte katselmoinnin tehtävän.

Projektin katselmointi

Löydätte kaltsemoitavan repositorion linkin Moodle-alueen etusivulta “Tiimit”-osiosta tiiminne kohdalta.

Katselmointi suositellaan tehtäväksi koko tiimin voimin joko lähityöskentelynä tai hyödyntäen esimerkiksi Discordia tai ia ruudunjakoa. Katselmoinnin yhteydessä käytävä keskustelu on myös erinomainen tilaisuus oppia itse.

Google on dokumentoinut omia katselmointikäytäntöjään “Best practices”-sivuilleen ja “How to do a code review”-dokumenttiin.

Tässä katselmoinnissa ei ole tarpeen puuttua kaikkiin mahdollisiin koodissa oleviin haasteisiin ja keskeneräisyyksiin, vaan painottaa sellaisia asioita, joihin pystytte kontribuoimaan positiivisesti.

Nimeäminen, ymmärrettävyys, kommentointi ja koodin rakenne voivat olla hyviä ehdokkaita palautteelle. Jos jokin kohta koodissa vaikuttaa tarpeettoman monimutkaiselta, yrittäkää pohtia, miten sitä voitaisiin pilkkoa osiin tai yksinkertaistaa ja liittäkää ehdotus mukaan palautteeseenne.

Muistakaa positiivinen henki

Toisen työn kommentointiin liittyy aina riski kritiikin aiheuttamasta tarpeettomasta mielipahasta. Pyritään siis löytämään kaverin koodista hyviä piirteitä ja antamaan konkreettisia kehitysehdotuksia pelkän kritiikin sijasta. Otetaan myös palaute vastaan hyvillä mielin: kukaan ei odota tiimien työn olevan täydellistä ja tämänkin työvaiheen tarkoitus on kehittyä ohjelmistokehittäjinä.