Kóðarýni

Leiðbeiningar um hvernig á að framkvæma gagnlega og uppbyggilega kóðarýni.

Hvernig við lesum vinnu hvers annars

Kóðarýni (code review) er mikilvægur hluti af þróunarferli sem tryggir að kóðinn sé skiljanlegur, öruggur og vel skrifaður. Rýnir ber ábyrgð á því að hjálpa til við að bæta gæði kóðans áður en hann er sameinaður aðalgreininni.

Af hverju er kóðarýni mikilvæg?

  • Tryggir gæði kóðans – Hjálpar til við að finna villur og betrum bæta lausnir.
  • Deiling þekkingar – Nýir liðsmenn læra af betri kóðunaraðferðum.
  • Tryggir samræmi – Gæti að verkefnið fylgi stöðluðum forritunarvenjum.

Hlutverk rýnanda

  • Fara yfir breytingarnar í smáatriðum.
  • Ekki samþykkja PR í blindni – Vertu viss um að skilja kóðann.
  • Óska eftir útskýringum ef nauðsynlegt er.
  • Keyra kóðann sjálfur og prófa virkni.
  • Vera uppbyggilegur í athugasemdum.
  • Nota inline comments fyrir skýra tilvísun í kóða.
  • Nota suggestion virknina til að leggja fram breytingar án þess að skrifa yfir kóða beint.
  • Ef kóðinn virkar ekki eins og til er ætlast, sýna skjáskot af villunni eða óvæntri hegðun.

Hvað á að skoða í kóðarýni?

1. Skiljanleiki og læsileiki

  • Er kóðinn auðlesanlegur og vel skipulagður?
  • Nota nafngiftir skýrt og lýsandi heiti?
  • Hefur verið forðast óþarfa flækjur og hringtengingar?

2. Villuleit og stöðugleiki

  • Getur þessi kóði leitt til óvæntra villna?
  • Hafa verið prófanir fyrir breytingarnar?
  • Er kóðinn þolinn fyrir röngum inntökum?

3. Fylgni við verkefnastöðlun

  • Fylgir kóðinn kóðastíl verkefnisins?
  • Passar breytingin við arkitektúr verkefnisins?

4. Afköst og skilvirkni

  • Er kóðinn of flókinn fyrir einfaldan tilgang?
  • Hefði verið betra að nota aðra nálgun sem er hraðvirkari?

Hvernig á að gefa góða endurgjöf?

Dæmi um góð og slæm endurgjöf

Góð endurgjöf

Mjög flott útfærsla! Hins vegar, gætirðu notað `map()` hér í stað `for` lykkju til að einfalda kóðann?
Þetta virkar vel, en mér finnst skýrleikinn betri ef við skiptum þessu í minni aðgerðir. Gætirðu búið til fall fyrir þessa útreikninga?
Sjá skjáskot hér að neðan – úttakið er ekki eins og til er ætlast. Gætirðu athugað hvað veldur þessu?
![Skjáskot](https://example.com/error_screenshot.png)

Ógagnleg endurgjöf

Mjög flott, virkar.
Þetta er ekki gott. Lagaðu þetta.
Ég skil ekki kóðann.

Nota inline comments og suggestion

Í GitHub PR er hægt að gera athugasemdir við einstakar línur með inline comments. Einnig er hægt að nota suggestion til að sýna tillögur á breytingum:

```suggestion
for item in list_of_items:
    process(item)
```

Ef um Markdown skjal er að ræða, er hægt að nota suggestion til að lagfæra kóðablokkir:

````suggestion
```python
# Endurbætt útgáfa
for item in list_of_items:
    process(item)
```
````

Þetta gerir það auðveldara fyrir forritara að taka tillit til breytinga án þess að rýnir breyti beint í kóðann.

Samþykki, synjun og beiðni um breytingar

Í kóðarýni er hægt að:

  • Samþykkja PR – Þegar kóðinn uppfyllir allar kröfur.
  • Óska eftir breytingum – Þegar þarf að laga hluti áður en hægt er að samþykkja.
  • Setja athugasemdir án þess að hindra PR – Til að gefa uppbyggilega endurgjöf án þess að krefjast breytinga.

Regluverkið í mannamáli

Á kóðageymslum námskeiðsins gilda reglur um greinavernd (branch protection). Í mannamáli þýða þær:

  • ekki má eyða main eða skrifa yfir Git-söguna með force push,
  • breytingar fara inn í main með pull request,
  • að minnsta kosti tveir rýnar þurfa að samþykkja PR-ið, og þeir mega ekki vera sá sem sendi breytinguna inn,
  • ef ný commit bætast við eftir rýni þarf að rýna aftur,
  • PR-ið þarf að vera up to date áður en það er sameinað,
  • allar umræður í review threads þurfa að vera leystar áður en hægt er að merge-a.

Tilbúið ruleset-sniðmát er hægt að afrita inn í eigin kóðageymslu: farið á GitHub síðu kóðageymslurnar undir Settings → Rules → Rulesets (https://github.com/<owner>/<repo>/settings/rules) og veljið Import a ruleset.

MikilvægtUndantekningar frá reglunum

Reglurnar hér að ofan gilda um alla í teyminu. Aðeins notendur með tiltekin réttindi geta samþykkt undantekningar frá þeim — til dæmis að sameina PR án þess að farið hafi fram full rýni.

Í þessu námskeiði er kennari námskeiðsins einn undanþeginn þessum kvöðum og hefur þessi réttindi. Nemendur og verkefnastjórar geta því ekki veitt sjálfum sér eða öðrum undanþágu frá reglunum; slíkt þarf alltaf að fara í gegnum kennarann (þ.e.a.s. organization administrator kóðageymslurnar).

AthugasemdAf hverju þetta skiptir máli fyrir verkefnastjóra

Í capstone-verkefninu eru teymin þriggja manna. Verkefnastjóri hverrar lotu, sem þarf að geta staðið skil á vinnu hópsins í iTA, hefur því yfirleitt annaðhvort verið PR-höfundur eða PR-rýnir á öllum greinum sem voru sameinaðar inn í main.

Ef verkefnastjóri hefur sinnt PR-rýninni nægilega vel ætti hann að vera vel kunnugur verkefninu: hvað var gert, hver gerði hvað, hvers vegna breytingarnar voru samþykktar og hvernig þær tengjast capstone-verkefninu.