Kildekode uten versjonskontroll er utenkelig, men hvordan forvalter du ideer, beslutninger, erfaringer eller andre gullkorn i applikasjonen din?

Er du avhengig av noen nøkkelpersoner som husker alt? Ligger gullet begravet i hundrevis av jira-saker som snart er glemt? Eller har du som mange andre en overflod av Confluencesider med en salig blanding av AS-IS, TO-BE, WAS eller MAYBE beskrivelser?

Jeg vil slå ett slag for at gullet bør følge kildekoden. La all applikasjonskunnskap som kan gjøres utdatert med en commit ligge sammen med kildekoden.

Tanker, ideer, beslutninger og erfaringer må leve ett sted der de kan kommuniseres, diskuteres og foredles sammen med kildekoden. La det være en helt naturlig del av kodegjennomgang og også oppdatere “notatene” som påvirkes av kodeendringene. De gamle gullkornene er kanskje ikke like lure lenger og glir over til å bli erfaringer eller kanskje til og med bare slettes.

Jeg ser ikke på det som dokumentasjon for ettertiden, men mer som modelleringsleire. Leire som vi skal forme samtidig som vi lærer og løfter løsningen vår til nye høyder. Det at det kan bli bra dokumentasjon av det til slutt, er bare ett biprodukt.

Jeg er utvikler - ikke forfatter eller arkitekt

Det er ingen grunn til å skrive masse prosa rundt koden din. Den skal stå stødig på egne ben sammen med sine tester. Fokuser på å få frem det som har ført til at den ser ut som den gjør.

Form og farge på innholdet vil sikkert variere ut i fra hva slags applikasjon du lager. Jeg liker denne strukturen i README.md filen min

Kontekst

Det blir ikke gode løsninger bare fordi du skriver god kode, du må faktisk forstå veldig mye av konteksten rundt applikasjonen. For meg handler denne konteksten om

  • Aktører som er premissgivere eller mottakere av det vi skal lage
  • Mål/hensikt for de ulike aktørene
  • Begrep som handler om det organisasjonen driver med
  • Regler og beste praksis skal beskrive hvordan en organisasjon faktisk har tenkt å innfri målsetningene
  • Hendelser og prosess definerer alt det viktige som vil, eller kan, inntreffe og hvordan dette blir håndtert.

Det er ikke nødvendig å skrive veldig mye prosa rundt dette, men viktig å få med de viktigste “knaggene” som kan inspirere til videre informasjonsinnhenting.

Lag en tabell som viser de ulike aktørene og deres målsetning. Legg inn noen stikkord. Skill mellom hva som er del av oppgaven til denne applikasjonen og hva som faller utenfor scope. Det er ett fantastisk verktøy til å strukturere senere diskusjoner og ikke minst artig for ettertiden å se hvordan denne tabellen vokser etter hvert som vi forstår mer og mer av det som faktisk må løses.

Husk stikkordsform og fint med referanser til mer utfyllende materiale.

Eksempel på aktører og deres forventninger i fra system for orienteringsarrangement :

Lag en liste over viktige regler som skal bidra til hver hensikt/målsetning.

Ett eksempel kan være:

Lag figurer - det sier mer enn ord. Bruk tekstbaserte modeller ala plantuml slik at endringer i “figuren” lett kan sees ved en diff i en commit. Lag deg en egen “notasjonsform” som gjør det effektivt å jobbe med tekstbaserte modeller. Det er ikke veldig viktig med perfekt notasjon. Det viktigste er de store boksene og pilene.

@startuml
hide footbox

participant Deltagerbrikke as pdb
participant Postenhet as ppe
participant meldestasjon as pms
database "emittiming" as dbe
activate pdb
pdb -> ppe : "stempling"
activate ppe
ppe --> pdb: postkode + tid
deactivate pdb
ppe -> pms: brikkenummer\n + tid + postkode
deactivate ppe
activate pms
pms -> dbe : last opp til server
deactivate pms

@enduml

Som vises som

Diagram er billig modelleringsleire. De må formes, diskuteres og foredles.

Vis begrepsmodellen og beskriv de viktigste entitetene. Her er et nok ett eksempel i fra orienteringsverden.

Etter hvert som vi lærer, så er det helt naturlig å også oppdatere vår kunnskap i README.md

Her er ett eksempel knyttet til endringer av domenemodellen

Andre henger seg på og legger til sine erfaringer og tanker

… og ikke minst modellene forteller mer enn ord

Beslutninger

Løsningens arkitektur er summen av våre viktige beslutninger. Disse beslutningene må få spalteplass. Noen beslutninger kan godt støttes med noen stikkord om begrunnelsen. Kanskje det er noen erfaringer som er viktig å kjenne til for å forstå bakgrunnen?

Jeg liker å ramse opp beslutninger innenfor kategoriene - funksjonelle og tekniske.

Eksempler på funksjonelle beslutninger kan være:

  • hvordan flyten i applikasjonen skal være
  • ulike forutsetninger vi legger på tilstøtende applikasjoner
  • viktige endringer i fra tidligere versjoner
  • funksjonalitet som er utenfor scope
  • språkstøtte

Eksempler på tekniske beslutninger kan være

  • valg av ulike bibliotek - hvor mange måter skal vi parse json på egentlig.
  • eventuelle rammeverk
  • viktige utviklingsprinsipper
  • håndtering av konfigurasjon
  • håndtering av secrets
  • provisjonering av infrastruktur
  • feilhåndtering og logging

I korte trekk - en oppsummering av det vi har blitt enige om. Det hender jo at det blir omkamper - og da er det jo fint at kan kjøre debatt i en Pull-request

Utvikling

Hvordan komme i gang?

Den beste måten å komme under huden på en applikasjon, er å se den i aksjon. Det er derfor viktig at vi har en detaljert og repeterbar beskrivelse av hva som faktisk skal til for kjøre applikasjonen i utviklingsmiljøet - uten fare for omgivelsene.

Andre nyttig elementer kan være:

  • Beskriv katalogstrukturen i prosjektet
  • Oppsett og rutiner ved eventuell kodegenerering

Arbeidsflyt

Hvilke regler har vi definert for vår arbeidsprosess

  • Commits og PullRequests
  • Testing
  • Konfigurasjonsparametre
  • … og selvfølgelig … foredling av gullkorn og erfaringer

Utrulling

For skreddersøm applikasjoner - er det like greit og også inkludere beskrivelser av byggeprosesser og hva som skal til for å provisjonere nye versjoner ut i ulike miljø.

Andre nyttige elementer, kan være:

  • Hva er manuelt og hva skjer automatisk?
  • Hvordan starte nye instanser for å teste ny funksjonalitet?
  • Beskrivelse av de ulike miljøene som benyttes og prosesser for å få tilgang til disse.
  • Hvordan håndterer vi konfigurasjon?

Drift

For skreddersøm applikasjoner - så kan også driftserfaringer og rutiner beskrives.

Dette kan være:

  • Overvåkning og monitorering
  • Effektiv feilsøking
  • Typiske feilsituasjoner
  • Normale driftsprosedyrer
  • Hvilke grep er trygge å iverksette?
  • Hvilke grep krever planlegging og nedetid?

Integrasjoner

Denne er viktig og krever helt klart en figur som viser de tilstøtende systemene. Jeg synes det gir mye verdi å starte tidlig med å se på integrasjonspunktene for en applikasjon. Det gir meg en rask onboarding i ett nytt domene

  • hvilke begrep eksisterer ?
  • hvilke hendelser og prosesser intitierer informasjonsutveksling?
  • hvilke regler gjelder for behandling av informasjonen?

Alle systemer har sin “natur” og det tar tid å bli kjent. Fint å dokumentere erfaringene underveis sammen med:

  • kontaktpersoner
  • ansvarsdeling mellom systemene (hvem eier de ulike delene av domenemodellen)
  • ulike miljø og rutiner for få tilgang
  • dokumentasjon av skjema

Hva med arkitekten?

Hva med arkitektene som dekker flere prosjekt og applikasjoner og skal styre utviklingen mot ett større målbilde. Skal de også skrive dok sammen med kildekoden?

Nei det gir ikke mening, men lov meg to ting

  • arkitektene må være med på “review” av tanker, ideer og beslutninger
  • arkitektene skal slippe å grave for å finne ut hvordan ting fungerer i eksisterende løsninger. Det skal holde å finne kildekoden.