Når Teodor spør om tanker rundt hva som er god kode, så vil jeg benytte anledningen til å peke på et kjennetegn som jeg blir glad og takknemlig av å finne i et repo. 🥰

God kode er dyttet ut med en commit laget av noen som har gjort et forsøk på å pakke endringen sin pent sammen, og skrive en melding som forklarer kontekst. Noen ord om hva i en kort oppsummering i tittel på committen, etterfulgt av en beskrivelse av hvorfor endringen ble gjort.

Git er dokumentasjon

Historikken i et Git repo kan være ugjennomtrengelig og tilnærmet meningsløs — eller det kan være den beste dokumentasjonen som fins om koden. Når jeg skal lese kode skrevet av andre, eventuelt skrevet av meg selv for tre uker siden, så leter jeg etter kontekst i commit-meldingene. GitHub beskriver at:

Commits are a firsthand historical record of exactly how and why each line of code came to be. They even come with human-readable messages! As a result, a repository’s commit history is the best tool a developer can use to explain and understand code.

Det beste verktøyet for å forstå kode! 🦾 Men det kommer an på hvordan du og meg lager våre commits, om vi gjør det med en intensjon om å forklare.

Form på en god commit-melding

Oppsummering om HVA på under 50 tegn

Beskrivelse av HVORFOR denne koden skal inn i repoet, forklart på det
tidspunktet der den som lager denne committen fortsatt har den beste
forståelsen av årsak til endringen. Den konteksten blir fort tapt.

Høres det vanskelig ut? Tidkrevende og kronglete? Som med alt annet vi driver med, det går an å øve og så blir det enklere å skrive gode beskrivelser som en naturlig del av arbeidsflyten. Hvis man virkelig ikke klarer beskrive hvorfor en endring skal gjøres, kanskje det ikke er en nødvendig endring?

Eksempler på nyttig kontekst

Kanskje jeg vet noe som ikke nødvendigvis en reviewer er kjent med:

Remove CPU limit for deployment of cheesecake

This change is done because SRE recommends disabling CPU limits,
Kubernetes pods always get the needed CPU from CPU requests.
Learn more: https://home.robusta.dev/blog/stop-using-cpu-limits

Trenger alle commit-meldinger en beskrivelse? Kan ikke endringen være selvforklarende?
Joda, noen endringer er det:

Upgrade dependency SuperDuperOven 2.3

Men kode er som regel ikke så selvforklarende som vi som kodere liker å tro på. Kanskje har vi oppdaget noe vi ikke kjente til da koden først ble skrevet, da er det en kul investering å forklare og dokumentere dette for dem som skal gjøre en review. Og for utviklere som skal sette seg inn i koden seinere:

Refactor chocolateCake.js

Because we found a bug in the previous implementation! If there are too
many cakes, some of them will not bake properly. This batch limit seems
like a good idea we want to try. Hopefully the new SuperDuperOven 3 will
support continuous baking so that we can remove this limit later.

Kan ikke en sånn forklaring stå i PRen? Jo… men det er lenger vekke fra koden. Dokumentasjon vi skriver i pull request, på et issue, på et trello-kort; ingen av disse stedene er like nærme og uløselig knyttet til koden som en commit-melding.

Og i motsetning til kodekommentarer, så blir forklaring i en commit-melding aldri utdatert. Tvertimot så stabler de seg pent oppå hverandre og forteller en historie som kan være nyttig for fremtidige utviklere:

Remove cake limit

This change was made because after migrating to SuperDuperOven v3
and testing over a couple of weeks with an increased limit for cakes,
we think it will be fine to now remove the limit. Non-stop chocolate!

Lær mer om hva andre mener

Det er mange som har skrevet mye bra om hvorfor det betyr noe hvordan vi lager commits:

Beskrivelse av hvorfor denne endringen er gjort. (Hva var problemet eller saken som skulle løses?) Vi commiter ikke kode inn i repoet helt uten grunn, det pleier å være en årsak til de endringene vi gjør.
— NAV IT: Om å skrive gode commit-meldinger

[Commits] are snapshots of your entire repository at specific times…based around logical units of change. Over time, commits should tell a story of the history of your repository and how it came to be the way that it currently is.
— GitHub: Git Guides

a well-crafted Git commit message is the best way to communicate context about a change to fellow developers (and indeed to their future selves)
— cbeams: The seven rules of a great Git commit message

Og reprise av dette første sitatet med lenke til teksten den kommer fra:

Commits are a firsthand historical record of exactly how and why each line of code came to be. They even come with human-readable messages! As a result, a repository’s commit history is the best tool a developer can use to explain and understand code.
— GitHub: Write Better Commits, Build Better Projects

— Elisabeth