Stilhåndbøker for prompts: Oppnå konsistent kode over alle sesjoner

Har du noen gang åpnet en kodebase og tenkt: “Hvem skrev denne delen? Det føles som om to forskjellige mennesker har jobbet her.”? Det er ikke et tegn på dårlig utvikling. Det er et tegn på at det ikke finnes en stilhåndbok.

Kode er ikke bare en instruksjon til maskinen. Den er en kommunikasjon mellom mennesker. Når du skriver kode, skriver du ikke bare for at den skal kjøre. Du skriver for at en annen utvikler - kanskje deg selv om seks måneder - skal forstå den. Og når flere mennesker jobber med samme kodebase, blir det viktig at alle skriver på samme måte. Ikke fordi det er et krav. Men fordi det reduserer forvirring, øker hastigheten og fjerner feil.

En stilhåndbok for kode er ikke en bok med regler som noen sjef har lagt ned på et bord. Den er en avtale mellom teamet. En enkel, praktisk guide som sier: “Her er hvordan vi skriver kode sammen.” Den handler ikke om å gjøre det perfekt. Den handler om å gjøre det konsistent.

Hva som virkelig teller i en stilhåndbok

Mange tror at en stilhåndbok handler om hvor mange mellomrom som skal brukes til innrykk. Eller om man skal ha semikolon på slutten av linjer. Det er deler av det. Men de viktigste delene er mye dybere.

• Naming: Skal variabler være camelCase eller snake_case? Skal klasser starte med stor bokstav? Hva heter en funksjon som henter brukerdata - getUser, fetchUser, eller loadUserFromAPI? Konsistente navn gjør det lett å forutsi hva en funksjon gjør, uten å måtte lese gjennom koden.
• Formatering: Hvor lange linjer skal være? Hvor skal krøllparenteser plasseres? Hvor mange tomme linjer mellom funksjoner? Når alt ser ut på samme måte, slipper hjernen å lete etter mønstre. Den kan fokusere på logikken.
• Kommentarer: Når skal du skrive dem? Hva skal de inneholde? En kommentar som sier // henter bruker etter en funksjon som heter getUser() er unødvendig. En kommentar som forklarer hvorfor en bestemt løsning ble valgt - fordi en annen løsning feilet i produksjon - er gull.
• Funksjoner og klasser: Hvor lange skal funksjoner være? Hvor mange parametre er for mye? En funksjon med 12 parametre er vanskelig å teste, forstå og endre. En regel som sier “maks 5 parametre” gjør at teamet tenker på strukturen før de skriver.
• Feilhåndtering: Hvordan håndterer dere feil? Med try/catch? Med spesielle feilmeldinger? Med logging? Når alle gjør det på samme måte, blir det lettere å spore feil og håndtere dem.

Det er ikke nødvendig å ha 100 regler. En god stilhåndbok starter med 5-10 regler som virkelig gjør forskjell. Og så bygger den seg videre - bare når det faktisk er et problem.

Automatisering er ikke valgfritt - den er grunnlaget

Hvis du måtte sjekke hver linje kode manuelt for å se om den passer til stilhåndboken, ville du blitt gal. Og teamet ville sluttet å bruke den.

Det er her verktøy kommer inn. Lintere og formatters gjør det umulig å skrive kode som ikke passer. De gjør det automatisk. Og de gjør det i bakgrunnen.

• ESLint for JavaScript/TypeScript - sjekker for feil, uklar struktur og ikke-konsistent stil.
• Prettier - formaterer hele filen automatisk. Ingenting du skriver kan unngå å bli formatert.
• Black for Python - en formatter som ikke lar deg velge stil. Den har én stil. Og den er god.
• clang-format for C++ og C - holder koden i linje med C++-standarden.

Disse verktøyene integreres i din editor, og de kjører automatisk når du lagrer filen. De kjører også i CI-pipelineen - så ingen kode som ikke passer, kan bli merget.

Team som bruker disse verktøyene, bruker 89 % mindre tid på å diskutere stil i kodegjennomganger. Det er ikke en liten ting. Det er 11 timer i uken som blir fri for å løse virkelige problemer - ikke for å diskutere om man skal ha mellomrom før eller etter parenteser.

Hvorfor stilhåndbøker reduserer feil

Det er ikke bare fordi det ser penere ut. Det er fordi hjernen din er god til å oppdage mønstre - og dårlig til å oppdage unntak.

Når alt er konsistent, blir en feil som ser ut som if (user.id == null) i en fil der alle andre bruker ===, umiddelbart synlig. Den stikker ut. Den er som en rød tråd i en hvit vev.

En studie fra Graphite i 2023 viste at team med konsistent stil reduserte antall innførte feil med 18 %. Ikke fordi de var bedre utviklere. Fordi de kunne se feil lettere.

Og når du skal forstå gammel kode? En kodebase som er skrevet av tre ulike mennesker over tre år blir en mørk skog. Men hvis alle har fulgt samme stil, blir den en lys sti. Du kan lese den som en bok - ikke som et puslespill.

Hva som ikke skal være i en stilhåndbok

Ikke alle regler er like viktige. Og noen regler er bare forstyrrende.

Her er hva du bør unngå:

• Regler som ikke har en grunn: “Ingen trailing kommaer.” Hvorfor? Hvis ingen kan si hvorfor, så skal den ikke være der.
• For mange regler: En stilhåndbok med over 120 regler øker utviklerfrustrasjon med 32 %. Det er ikke en overdrivelse. Det er en faktisk måling fra Broad Institute.
• Regler som ikke kan automatiseres: Hvis du må sjekke det manuelt, vil det ikke bli gjort. Det er bare tid og energi som går til spille.
• Regler som bare en person liker: Hvis sjefen insisterer på at alle skal bruke underscore_case fordi han likte det på en reise til Japan - så vil teamet ikke følge den. De vil bare deaktivere linteren.

En god stilhåndbok blir ikke laget av én person. Den blir laget av teamet. Med en enkel regel: “Vi legger til en regel bare når vi ser at den forhindrer en feil eller forvirring.”

Hvordan starte - uten å bli overveldet

Du trenger ikke å starte med en 50-siders PDF. Du trenger ikke å endre hele koden på en dag.

Her er en enkel plan:

1. Velg et verktøy: Hvis du bruker JavaScript - sett opp Prettier og ESLint. Hvis du bruker Python - sett opp Black og Flake8. De kommer med standarder som fungerer ut av boksen.
2. Kjør dem på ny kode: Ikke endre gammel kode. Bare la nye filer følge reglene.
3. Legg til én regel om gangen: Hvis du ser at folk skriver funksjoner med 20 parametre - legg til en regel som sier “maks 5”. Hvis du ser at folk bruker både == og === - legg til en regel for streng sammenligning.
4. Legg det til CI: Sørg for at ingen kode kan merges hvis den ikke passer.
5. Gjør det til en del av onboarding: Når en ny utvikler kommer inn, vis dem ikke koden. Vis dem stilhåndboken. Og la dem se hvordan verktøyet fungerer.

Det tar 2-4 uker før teamet blir vant. Det tar 8-12 uker før det blir naturlig. Men når det skjer - blir koden lettere å lese, lettere å endre, og lettere å vedlikeholde.

Hva skjer med AI og stilhåndbøker?

AI-verktøy som GitHub Copilot har nå blitt “stilbevisste”. De ser på hva du har skrevet før, og foreslår kode som passer til din stil - ikke bare til språket.

I mars 2024, lanserte SonarSource en ny versjon av SonarQube som bruker AI til å anbefale stilregler basert på din egen kodebase. Den ser på hva som er vanlig i prosjektet - og foreslår regler som faktisk vil hjelpe.

Det betyr at fremtiden ikke er mer regler. Det er smartere regler. Regler som forstår kontekst. Regler som ikke kaster en masse krav på deg - men som hjelper deg å skrive bedre kode.

Sluttresultat: Kode som føles som én person har skrevet den

Det største målet med en stilhåndbok er ikke å gjøre koden penere. Det er å gjøre den forutsigbar.

Når du åpner en fil, vet du hva du skal forvente. Du vet hvordan variabler heter. Du vet hvordan funksjoner er strukturert. Du vet hvordan feil håndteres. Du vet ikke at du vet det - men du føler det.

Det er det som gjør at du kan bygge store systemer med mange mennesker. Det er det som gjør at du kan gå fra en liten ide til et produkt som tjener millioner.

En stilhåndbok er ikke en begrensning. Den er en frihet. Friheten til å fokusere på hva som virkelig teller: logikk, løsninger, og brukere.

Ikke skriv kode for maskinen. Skriv kode for menneskene - og la verktøyet gjøre resten.