Koddokumentation: The Complete Beginner’ s Guide
du är lite långt in i ditt första programmeringsjobb, och saker blir enklare. Först kan all kod du hade att göra med ha överväldigat och förvirrat dig, men du börjar få tag på det. Det är toppen! Nu undrar du hur du tar koden du skriver till nästa nivå. Även om det finns massor av saker att lära sig om din programmering stack, varav många kommer att göra dig till en bättre programmerare, finns det några som kommer att tjäna dig oavsett vilken stack du arbetar i. En av dessa är koddokumentation.
många utvecklare skriver inte tillräckligt med dokumentation, antingen för att de inte ser värdet eller för att de känner att de inte har tid. Du behöver inte vara en av dessa utvecklare. Med lite tid och mycket övning kan du lägga till dokumentation för din kod som gör det till en glädje att använda för både dig och alla andra som kommer med.
bra dokumentation finns i många former
när de flesta utvecklare tänker på koddokumentation tänker de på kommentarer. Kommentarer kan vara värdefulla tillägg till kod, men de är inte den enda definitionen av dokumentation. Dokumentation är allt du skriver utöver din kod för att hjälpa någon annan att förstå hur det fungerar. Du kanske inte tänker på det här sättet, men ett bra exempel på koddokumentation är en README-fil. Ett bra exempel på grundläggande dokumentation är Express.js README-fil. Den svarar på flera viktiga frågor om ramverket och berättar hur du kan inkludera det i ditt projekt, hur du installerar det och hur du kör test.
bra dokumentation kan också komma i form av API-dokumentation. Återigen, uttrycka.js ger ett bra exempel. Den här versionen av dokumentationen är mer ett referensbibliotek för utvecklare som använder ramverket. Du hittar svar på frågor om vad enskilda funktioner gör och vad olika parametrar för dessa funktioner betyder. Utan den kvalitetsdokumentationen skulle Express inte ha nästan lika många lag som använder det som de gör.
och naturligtvis kan du använda in-line kommentarer för att dokumentera kod också. Dessa typer av kommentarer brukar inte användas för att lära människor utanför ditt eget team om koden. Istället är de användbara för att förklara vad som händer i en viss bit kod till dina lagkamrater eller till ditt framtida jag.
varför ska du dokumentera din kod
som nämnts ovan förstår många utvecklare inte syftet med koddokumentationen. De kommer att hävda att bra kod ska vara självdokumenterande och att du inte behöver förklara det. Dessa människor är, i ett ord, fel. Sanningen är att bra dokumentation är en viktig del av någon kodbas. Varför? Eftersom människor inte borde behöva läsa all din kod för att förstå vad den gör. “Människor” i den föregående meningen kan hänvisa till vem som helst, inklusive ditt framtida jag.
sanningen är att ofta är de “människor” som behöver förstå koden efter att den är skriven du. Den lilla logiken som verkade så smart när du skrev den för sex månader sedan kan vara svår att förstå idag. Om din kod är väldokumenterad behöver du inte spendera tid på att försöka förstå vad den gör. Du kommer att kunna spendera några sekunder på att titta på beskrivningen och sedan komma tillbaka till vad du arbetar med just nu.
om du har turen att arbeta med kod som används av dussintals eller hundratals utvecklare är bra dokumentation ännu viktigare. Användarnas liv kommer att förbättras avsevärt genom din tid att skriva bra dokumentation, och de kommer att tacka dig för det. Bokstavligen!
nyckeln till att komma ihåg är att bra dokumentation sparar mer tid än det tar att skriva den. Det kan vara din tid, eller det kan vara tiden för lagmedlemmar, eller till och med människor du aldrig kommer att träffa. Ibland kan skrivdokumentation till och med hjälpa dig att känna igen en del av din kod som är för komplicerad så att du kan förenkla den.
några vanliga Dokumentationsfel
som juniorutvecklare måste du spendera tid på att lära dig vad som gör dokumentationen effektiv. Den goda nyheten är att du kan lära av människor som har gått före dig så att du kan undvika vanliga misstag.
Underdokumentation
ett vanligt misstag jag ser med koddokumentation är att dokumentera information som redan är tydligt synlig. Till exempel kommer lazy developers att lägga till “dokumentation” till en funktion genom att lägga till ett block som ger namnet på en funktion samt namnen på varje parameter och deras enskilda typer. Denna typ av dokumentation är värdelös! Det tar sekunder för någon att läsa namnet på funktionen och parametrarna som krävs. Det är inte dokumentation, det är bara upprepning. I stället bör dokumentationen innehålla en snabb bit av information om vad funktionen gör och hur varje parameter ändrar funktionens beteende eller varför det behövs.
Överdokumentation
det motsatta mönstret kan också vara ett allvarligt problem. För att undvika att skriva för lite dokumentation gillar vissa utvecklare att skriva ut förklaringen för varje liten bit av logik som finns i en funktion. De dokumenterar noggrant varje motiv som gick till att skapa funktionen. När de är färdiga kan de ha spenderat så länge att skriva funktionen som de skrev dokumentationen. Vad som är värre är att dokumentationen ofta är svår att förstå och tar lika lång tid som att läsa koden. Den typen av dokumentation är också slöseri med tid. I stället ger bra dokumentation en grundläggande förklaring av både vad och varför. Om det finns några särskilt knepiga delar av koden att förstå, bör dokumentationen förklara just dessa delar.
förlita sig på tester för att dokumentera
ibland kommer du att stöta på någon som hävdar att den bästa formen av dokumentation är enhetstester. Det tillvägagångssättet har en stor brist: läsenhetstester är ofta lika svåra att göra som att läsa själva koden. Alla utvecklare som vill lära sig vad din kod gör kommer att ha ett stort första steg medan de jagar och läser alla dina enhetstester. Många kommer bara att ge upp innan de uppnår vad de vill göra. Medan enhetstestning är ett värdefullt tillskott till någon kodbas, är det inte en ersättning för bra dokumentation.
sätt att ta dokumentation till nästa nivå
om du arbetar på en stor kodbas kan koddokumentation kännas skrämmande, särskilt om du inte har varit flitig med att dokumentera kod fram till denna punkt. Det kan kännas som om du försöker koka havet. Om du har en stor kodbas, eller en där du vet att bra dokumentation är kritisk, kanske du vill undersöka automatiserade koddokumentationsverktyg. Dessa verktyg förenklar drastiskt processen att skriva konsekvent, bra dokumentation för ett helt team. Ett verktyg som GhostDoc kommer intelligent titta på din kod och använda mallar som fastställts av ditt team för att få igång din dokumentation med ett par knapptryckningar. Automatiserade dokumentationsverktyg tar bort en av de andra vanliga anledningarna att motsätta sig att skriva dokumentation: det tar för mycket tid.
när du har konsekvent dokumentation kan du enkelt dela den dokumentationen med andra verktyg. Automatiserade dokumentationsverktyg tar smärtan av att utveckla bra dokumentation för saker som offentliga API: er som din kod tillhandahåller.
Kom igång idag
att skriva bra dokumentation är mycket enklare än att skriva kod. Till skillnad från kod är dokumentation inte ett allt-eller-ingenting-företag. Börja med ett mål att skriva bra dokumentation för en funktion varje dag. Den typen av övning bygger hälsosamma vanor, och du kommer att se utbetalningen på vägen när du spenderar mycket mindre tid på att försöka förstå delar av din kodbas. Med tiden börjar det kännas fel när du skriver kod som inte har bra dokumentation. Du börjar påpeka sätt att förbättra dokumentationen till dina medarbetare under kodgranskning. En liten vana kommer att förbättra ditt lags kod för hela ditt företag.
lär dig hur GhostDoc kan hjälpa till att förenkla dina XML-kommentarer, producera och underhålla kvalitetshjälpdokumentation.
om författaren
Eric Boersma
Eric Boersma är en mjukvaruutvecklare och utvecklingschef som har gjort allt från IT-säkerhet inom läkemedel till att skriva underrättelseprogram för den amerikanska regeringen att bygga internationella utvecklingsteam för ideella organisationer. Han älskar att prata om de saker han lärt sig på vägen, och han tycker om att lyssna på och lära av andra också.
