Koddokumentation är samlingen av lättförståeliga bilder och skriftliga beskrivningar som förklarar vad en kodbas gör och hur den kan användas.
det kan vara enkla förklarande kommentarer ovanför funktioner och block, eller en fullfjädrad utvecklarhandbok, komplett med receptbelagd stil dos-and-don ’ ts, översikter över varje del av applikationen och tillvägagångssätt för de vanligaste typerna av kodningsuppgifter.
det är ofta bäst att hitta ett lyckligt medium mellan dessa två ytterligheter när du fattar det medvetna beslutet att kommentera din kod och skissera de gnarlier områdena i en kodbas i vanligt språk.
varför dokumentera din kod?
varför gå till problem att skriva om din kod, istället för att bara skriva kod? Skulle det inte bara vara mer produktivt ändå?
mentala spara poäng
dokumentation är som en mental spara punkt för de tider när du äntligen får vad som händer i slutet av dagen och inte vill förlora fart. Väl dokumenterad kod kommer att säkerställa att när du behöver dyka tillbaka i morgon morgon (eller flera månader från och med nu) behöver du inte ta så mycket tid att komma igång.
dokumenterad kod återanvänds
skillnaden mellan ett använt bibliotek och ett oanvänt bibliotek beror ofta på dess dokumentation.
Vem vill använda ett odokumenterat open source-bibliotek eller bidra till ett odokumenterat projekt? Nästan ingen.
i de flesta fall använder du hellre ett mindre kraftfullt bibliotek som har dokument. Varför? Eftersom dokumentationen förmedlar andra informationspunkter om en kodbas. Utvecklarna tror att projektet är värt den tid och energi att skriva om det i klartext så att alla som kan vara intresserade kan snabbt komma igång och lära sig hur det fungerar, och varför viktiga beslut fattades.
att hitta ett nytt, intressant och väldokumenterat projekt på ditt favoritspråk kan vara väldigt spännande och roligt. Låt oss titta på det extrema alternativet: att behöva använda ett odokumenterat kodbibliotek och potentiellt bidra till en till synes bysantinsk kodbas… det låter ganska smärtsamt, eller hur?
så varför har du inte dokumenterat din egen kod?
dokumentera kod är en del av att skriva bra kod
en hörnsten i bra kod är underhåll, uppnås genom begriplig, läsbar dokumentation.
det finns flera sätt att dokumentera kod:
- välja bra namn för variabler och funktioner
- lämna korta kommentarer i koden för att hjälpa till att ge sammanhang till framtida läsare
- lägga till illustrativa bilder som sekvens-och entitetsrelationsdiagram
- tillhandahålla API-dokument, som beskriver varje klass, metod, argument och returvärde
- använda ett statiskt skrivet språk, till exempel TypeScript (typer som dokumentation)
jämför två exempel
låt oss säga att du får lite data från ett backend API och” ingressing ” det – konvertera det till en mer användbar form för en front-end UI. Här är den första av två möjliga lösningar.
// wdgt.jsexport const converter = (w) => { wdgtHdr = { name: w.nm, id: w.id, ts: w.lastTS } wdgtDtl = { dtlId: w.dtlId, dtlName: w.dtlNm, openTS: w.oTS, closeTS: w.cTS } wdgtRev = w.revs.map((r) => { const { note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS } = r const rr = { assocId: prsn1Id, assoc: `${prsn1Fn} ${prsn1Ln}`, amount: amt, note: note, revTS: cTS, } return rr } return { wdgtHdr, wdgtDtl, wdgtRev }}ovanstående kod har potential att vara smärtsam. Du kan se med namnet att det här är en slags omvandlare som tar w som dess param.
det ser ut som att det returnerar en rubrik, kanske detaljer och något som kallas revs. Var kom revs från, förresten? Naturligtvis finns det inga detaljer om de inkommande variabelnamnen note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS… eller finns det? Är rr kort för returned rev? Vem kan säga.
låt oss titta på det andra exemplet.
// widget_utils.ts// widgetConverter :: widgetRespDTO -> widgetexport const widgetConverter = (wResp: widgetRespDTO): Widget => { const widgetHeader: WidgetHeader = { name: wResp.nm, id: wResp.Id, ts: wResp.lastTS), // timestamp } const widgetDetail: WidgetDetail = { id: wResp.widgetId, name: wResp.dtlNm, openTS: wResp.oTS, // timestamp closeTS: wResp.cTS // timestamp } // is nested inside of WidgetRespDTO // .map -> const widgetRevisions: ReadonlyArray<WidgetRevision> = wResp.revs.map((wRevs: WidgetRevisionsRespDTO): WidgetRevision => { // how that other team names their variables...! const { cmt, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS } = wRevs const comment: string = cmt const associateId: string = prsn1Id const associateName: string = `${prsn1Fn} ${prsn1Ln}` const amount: number = amt const revisionTS: number = cTS // unix timestamp, and "closeTS" fyi return { associateId, associateName, amount, comment, revisionTS, } } return { widgetHeader, widgetDetail, widgetRevisions, }}Wow, hur annorlunda! Den här funktionen finns i en util – fil, så huvudfilen är redan mindre rörig. Det är också skrivet i TypeScript istället för vanligt JavaScript, så vi har fördelen med typdefinitioner för att hjälpa oss.
vi konverterar widgetRespDTOs till widgets. även om vi förkortas har vi full kunskap om vad wResp är. Vi skapar en widgetHeader och en widgetDetail ,det är lätt att se. Vi förstår också vad oTS och cTS är. Vi kan säga WidgetRevisionsRespDTO s är kapslade inuti WidgetRespDTO.
någon mycket vänligt bytt namn på inkommande variabler så att alla som ser den här koden vet vad de är. Slutligen ser vi att ett Widget måste bestå av det returnerade {widgetHeader, widgetDetail, widgetRevisions} – objektet, eftersom det måste matcha returtypen Widget som anges högst upp.
vilken kod skulle du må bättre om du använder?
vem gynnar?
väldokumenterad kod gynnar många människor:
Junior Utvecklare
eftersom det är i klartext och lätt att förstå, dokumentation hjälper junior utvecklare och nya gruppmedlemmar känner sig trygga hoppa in i en kodbas. Detta förhindrar frustration och tidigt övergivande av en uppgift eftersom det blir för komplicerat för snabbt.
det är också bra för yngre utvecklare att skriva sin egen dokumentation så att de kan dela sin kod med andra och så att de kan få en bättre förståelse för sin kod.
Senior developers
genom att ta sig tid att dokumentera nu spenderar senior devs mindre tid på att förklara sin kod för andra i framtiden.
de kan också skriva mer komplex kod. Vanlig språkdokumentation låter andra använda den som en svart låda utan att behöva förstå det inre arbetet.
Team & open source-projekt
personalförändringar kan ge en enorm avmattning i ett projekt. Uppdaterad och väldokumenterad kod kan fungera som försäkring mot sådana avmattningar och låta de återstående teammedlemmarna ta ett steg tillbaka, granska koden från en hög nivå och besluta om den bästa åtgärden framåt och vid behov ombord nya anställda.
du
när du dokumenterar kod måste du sammanfatta den. För att sammanfatta ordentligt måste du kunna förstå det och hålla de olika delarna i huvudet samtidigt. Att skriva eller bidra till dokumentationen är en genväg för att verkligen förstå en kodbas, göra stora bidrag och känna sig som en stor del av ett bra team.
bra dokumentation kan torka upp vår kodningsupplevelse
som programmerare har du förmodligen hört talas om principen om inte upprepa dig själv som en nyckel till att skriva ren och kortfattad kod. Istället för att upprepa samma kodblock flera gånger, skriv en funktion som kan skrivas en gång och användas över hela din ansökan.
på samma sätt bör du och ditt team inte stöta på liknande problem och sedan återuppfinna hjulet varje gång du försöker lösa dem. Har du till exempel någonsin hört en av dina kollegor eller befunnit dig att säga:
”Agh, jag löste något mycket liknande det här men jag kommer aldrig ihåg hur jag gör det när det kommer upp… Jag borde nog skriva ner det någonstans, va?”
du befinner dig sedan skanna samma Stack Overflow trådar om och om igen.
spara dig själv och dina medarbetare denna sorg genom att följa andan i den torra principen och skriva ett dokument som du kan använda varje gång problemet kommer upp! Detta hjälper dig och andra i ditt team att spara tid och vara effektivare när du skriver enklare, mer hanterbar och effektivare kod.
hur har koddokumentation, eller bristen på sådan, påverkat dig?