PG 1.6 Dokumentation
Table of contents
- Vad är dokumentation?
- Varför behöver vi dokumentation?
- Kommentarer
- Readme
- Egen dokumentation
- Separat dokumentation
- Användbara länkar
Vad är dokumentation?
Beskriver arbetsprocessen. Allt som du skriver som hjälper till att förklara hur din kod fungerar. I första hand, skriva så bra kod som möjligt som är läslig och enkel att förstå.
Exempel
- Kommentarer
- Readme/textfil
- Namngivning
- Commit meddelanden i versionshantering
- Referensmaterial
- Förklaringar
- Exempel
Varför behöver vi dokumentation?
- Komma ihåg för sig själv
- Tydlig kommunikation
- Legacy kod (förklara tidigare kodbas och vad den bygger på)
- Nya arbetssätt/uppdateringar av dependencies kräver refaktorisering, vilket underlättas om det finns dokumentation
- Lära sig av misstag
- Sätta sig in i projekt
- Slippa upprepa sig
- Öka spårbarhet
- Kvalitetssäkring
- Vid uppdatering av kodbas
- Överlämning till någon annan
När behöver vi inte dokumentation?
- Enkel kod
- Självklar kod
- När namngivningen är självförklarande
Kommentarer
Vi ska kommentera koden där det behövs, där det inte är en självklarhet vad koden gör.
När ska kod kommenteras?
- När det inte är självklart vad koden gör (om det inte är självklart är det bra att i första hand försöka få koden självförklarande genom t.ex. namngivning, uppdelning osv)
- När läsaren behöver ett sammanhang för koden som inte är självklart
- När vi gör “fula” lösningar för att lösa problem med t.ex. prestanda, brist på tid, storlek på filer etc
- Komplexa algoritmer och datastrukturer (går de att förenkla?)
Vad/hur ska vi kommentera?
- Vad koden gör, argumenterar, returer osv, vilket problem den löser
- Varför behövs koden? (en del menar att detta ska vara utanför själva koden, i extern dokumentation)
När ska vi INTE kommentera?
- Hur bra/dåligt någonting är
- Om koden är självförklarande
Readme
Vi skriver readme för att
- Ha dokumentationen separerad från kodbasen
- Bilder och annat som är svårt att ha i själva koden
- För att visa vad projektet handlar om, vilka språk och ramverk som används t.ex.
- Hjälpa någon annan att komma igång med projektet
Vem skriver vi readme för?
- Användare
- Andra utvecklare
Vad ska den innehålla?
- Installation
- Vilken problem löser den här kodbasen
- Litet exempel
- Länkar till övrig dokumentation/referensmaterial
- Var finns källkoden
- Hur kan jag bidra?
- Issues (hur de hanteras)
- Licens
Egen dokumentation
- Skapa ett eget utility-bibliotek
- Skriv en utvecklingslogg, typ dagboksanteckningar för specifika projekt eller din utvecklingsresa i allmänhet
- Starta en blogg, podd eller spela in videos där du besrkiver hur du löser specifika problem
Separat dokumentation
När projektet växer och det behövs mer strukturerad dokumentation över kodbas för utvecklare/användare kan det vara bra att ha dokumentationen separat. Den bör då innehålla allt som inte får plats/hör hemma i själva kodbasen.
Exempel
- Designdokumentation
- API referens
- Wiki
- De som bidragit till kodbasen