Vi er ikke helt ferdig med sommerens store farsott i kode24-klubben; bygging av den fiktive brusappen brus.no.
Flertallet har så langt valgt:
- Vue.js som frontend-rammeverk
- Firestore som database
- Firebase for autentisering
- Node.js for API-ene
- DigitalOcean for hosting
- Sentry for debugging i produksjon
Denne uken ba vi klubbens 3.180 medlemmer forklare hvordan de ville dokumentert koden til appen, og svarene rullet inn.
Hvordan norske utviklere dokumenterer kode hører du i kode24-timen, og i tekstform under avspilleren. 👇
#1: Dokumentasjon i koden 🧾
Ikke uventet foretrekker de fleste utviklerne i tråden å dokumentere koden sin i selve koden.
- Jeg er glad i inline-dokumentasjon på funksjoner. Jeg har mest erfaring med PHP og der fungerer det veldig bra å trykke CTRL+Q i PhpStorm for å se dokumentasjon på en funksjon jeg kaller. Det hjelper også mye med beskrivende navn på variabler og funksjoner, forteller Anders Birkenes.
Vim, Emacs, Nova, VS Code - sånn har vi satt opp editorene våre
Men kommentering i kode kan gjøres på mange forskjellige måter. Det finnes nemlig drøssevis med forskjellige stiler og konvensjoner- slik som Java sin egne spesifikasjon.
Derfor er det ikke rart at flere uttrykker uenighet med Birkenes sin metode.
- Det er ikke mye til dokumentasjon for tredjepart som skal gå gjennom koden din, eller som bruker en annen IDE enn din, svarer Christian Wic.
- PHPdoc er så vidt jeg vet et standardisert format, parerer Birkenes.
- Vi fulgte Googles mantra til kode-dokumentasjon; Say what you mean, simply and directly, avslutter Christian Wick.
«Et annet aspekt er hvorfor noe ble løst på en spesifik måte - ikke hvordan det fungerer.»
#2: Dokumentere arkitektur 🏰
Selv om kommentering i kode ser ut til å være den foretrukne formen for dokumentering blant norske utviklere, gir det ikke et særlig godt overblikk.
Så hva gjør du når du ønsker å formidle en oversikt over hvordan en stor kodebase med avhengigheter henger sammen? Jo, da må du dokumentere selve arkitekturen.
- Start prosjektet som en modulær monolitt!
- For en applikasjon der det ikke står om liv eller helse så vil jeg fokusere på følgende: Arkitektur-overblikk, gjerne i diagramform om det er den mest effektive måten å kommunisere det på, og dokumentasjon av eksponerte API-er, forklarer Michael Odden.
- Et annet aspekt er hvorfor noe ble løst på en spesifikk måte, ikke hvordan det fungerer. For det dokumentasjonsbehovet virker Architecture decision records ganske lovende, forteller Eirik Stenestø Tenold.
- ARCHITECTURE.md i repo-root, som inneholder nettopp overordnet arkitektur og eventuelle gjennomgående retningslinjer og større avgjørelser tatt underveis. Her vil jeg også adressere hvorvidt det er aspekter som bør revurderes, legger Odden til.
#3: README.md 📝
README.md er et dokument skrevet i markdown-format som er blitt en bransjestandard for enkel dokumentasjon, spesielt på tjenesten Github.
- Jeg har README.md i rota av repositoriet med lenker til flere dokumenter i "/doc/"-mappa i samme repo. Disse skal inneholde en minimal arkitektur- og domeneoversikt, samt minimal "få prosjektet til å kjøre"-dokumentasjon, forteller Vegar Vikan.
- README.md i repo-root som inneholder hvordan du kjører applikasjonen i tillegg til tester, samt en intro til hva den faktisk er, skyter Michael Odden inn.
- README.md for developer quick start, nikker Eivind BS.
«De første ukene er all kode bare ræva.»
#4: Skriv bedre kode eller få bedre konsulenter 😫
Ikke alle er enig i at det er dokumentasjon som skal til, når andre utviklere klager på uleselig kode. Det finnes nemlig andre alternativer.
- Hvis de ikke forstår koden din, så er koden for dårlig. Kommentarer vil neppe hjelpe. Skriv om koden og bruk beskrivende navnsetting, messer Yngve Eriksen.
- Litt feil å si at kode er dårlig fordi du ikke forstår den. Det er en ødeleggende holdning til kolleger, i det minste, parerer Tom Erik Paulsen.
Nei, du er ikke idiot om du spør om hjelp
- Jeg ville ikke sagt det direkte til dem, men tenkt det i mitt stille sinn, svarer Yngve Eriksen med et flir.
Utvikler Vegar Vikan skyter inn en litt mer sober uttalelse i diskusjonen:
- Dette vet jeg også fra egen erfaring som ny i eksisterende kodebaser. De første ukene er all kode bare ræva. Må være komplett idioter som har skrevet det. Etter hvert som en får kontroll på domenet og ser litt mer av hvordan prosjektet har blitt til over tid er kanskje ikke ting så fryktelig dumt allikevel.
- Dersom jeg har benyttet react eller .net eller mongo eller what-ever og de ikke forstår dette, har vi enten hyra feil konsulenter, eller så får de oppsøke dokumentasjonen på disse verktøyene. Jeg blir ikke å dokumentere det, forteller Vikan og påpeker at det kan av og til være dårlige konsulenter inne i bildet.
#5: Samarbeid med andre 👋
Få påpeker verdien i å faktisk sette seg ned med nye utviklere og forklare koden, bortsett fra utvikler Svein Petter Gjøby.
- Å sette seg ned med det nye teamet og gå gjennom koden vil nok være bedre bruk av tiden enn å skrive dokumentasjon som få (les: ingen) vil lese. Dette skaper også en arena hvor man kan spørre om det er noe man stusser på.
«En annen god ting er API-dokumentasjon som er kjørbar.»
#6: Tredjeparts-verktøy 🔨
Det finnes flere tredjeparts-verktøy som hjelper utviklere med å presentere og til og med generere dokumentasjon. Klubbmedlemmene lister ut dem de foretrekker.
- Vi bruker dokumentasjon i svært stor grad på jobben min. Aller helst bruker vi Wecomplish til å dokumentere alt som ikke dokumenteres i koden. Det er et prosjektstyringssystem som sjefen har laget og fortsatt arbeider med. Dokumentasjon for Wecomplish ligger, selvfølgelig i Wecomplish, forteller Markus Igeland.
- En annen god ting er API-dokumentasjon som er kjørbar, tenker her da på OpenAPI Specification (Swagger og lignende) som gir mulighet for dokumentasjon, tester og eksempler på kall, forklarer Eirik Stenestø Tenold.
- For å se sammenhenger mellom tjenester kan verktøy som NewRelic eller Jaeger Tracing brukes for å gi en grafisk fremstilling av avhengigheter mellom tjenester basert på automatisk sporing av forespørsler. Sentralisert logging (Splunk, Google Cloud Logging, og så videre) er også veldig bra for å følge en request gjennom teknologi stacken (så lenge requestID sender rundt blant systemene), legger Tenold til.
Slik bygger norske utviklere API-er
Vi spurte utviklerne i kode24-klubben, og fikk alle svar under solen.