Kodedokumentasjon er samlingen av lettforståelige bilder og skriftlige beskrivelser som forklarer hva en kodebase gjør og hvordan den kan brukes.
det kan være enkle forklarende kommentarer over funksjoner og blokker, eller en fullverdig utviklerhåndbok, komplett med prescriptive stil dos-and-don ‘ ts, oversikter over hver del av søknaden, og tilnærminger til de vanligste typer kodingsoppgaver.
det er ofte best å finne et godt medium mellom disse to ytterpunktene når du tar den bevisste beslutningen om å kommentere koden din og skissere de skarpere områdene i en kodebase i vanlig språk.
hvorfor dokumentere koden din?
Hvorfor gå til problemer med å skrive om koden din, i stedet for bare å skrive kode? Ville ikke det bare være mer produktivt uansett?
Mentale Lagre Poeng
Dokumentasjon er som en mental lagre punkt for de gangene du endelig får hva som skjer på slutten av dagen og ikke ønsker å miste momentum. Godt dokumentert kode vil sikre at når du trenger å dykke tilbake i morgen morgen (eller flere måneder fra nå), trenger du ikke å ta så mye tid å komme opp til fart.
Dokumentert kode blir gjenbrukt
forskjellen mellom et brukt bibliotek og et ubrukt bibliotek kommer ofte ned til dokumentasjonen.
hvem vil bruke et udokumentert open source-bibliotek eller bidra til et udokumentert prosjekt? Nesten ingen.
I de fleste tilfeller vil du heller bruke et mindre kraftig bibliotek som har dokumenter. Hvorfor? Fordi dokumentasjonen formidler andre informasjonspunkter om en kodebase. Utviklerne mener at prosjektet er verdt tid og energi til å skrive om det i klartekst, slik at alle som kan være interessert kan raskt komme i gang og lære hvordan det fungerer, og hvorfor viktige beslutninger ble gjort.
Å Finne et nytt, interessant og godt dokumentert prosjekt på ditt favorittspråk kan være veldig spennende og morsomt. La oss se på det ekstreme alternativet: å være pålagt å bruke et udokumentert kodebibliotek og potensielt bidra til en tilsynelatende bysantinsk kodebase… det høres ganske smertefullt, ikke sant?
så hvorfor har du ikke dokumentert din egen kode?
Dokumentasjon av kode er en del av å skrive god kode
en hjørnestein i god kode er vedlikehold, oppnådd gjennom forståelig, leselig dokumentasjon.
det finnes flere måter å dokumentere kode på:
- velge gode navn for variabler og funksjoner
- legge igjen korte kommentarer i koden for å gi kontekst til fremtidige lesere
- legge til illustrerende bilder som sekvens-og enhetsrelasjonsdiagrammer
- gi API-dokumenter som beskriver hver klasse, metode, argument og returverdi
- ved hjelp av et statisk skrevet språk, for eksempel TypeScript (typer som dokumentasjon)
Sammenlign to eksempler
la oss si at du får noen data FRA en backend API og «ingressing» den-konvertere den til en mer nyttig form for en front-end UI. Her er den første av to mulige løsninger.
// 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 }}ovennevnte kode har potensial til å være smertefullt. Du kan se ved navn at dette er en slags omformer som tar w som sin param.
Det ser ut til at det returnerer en header, kanskje detaljer, og noe som kalles revs. Hvor kom revs fra, uansett? Selvfølgelig er det ingen detaljer om de innkommende variabelnavnene note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS… eller er det? Er rr kort for returned rev? Hvem kan si.
La oss se på det andre eksemplet.
// 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, så annerledes! Denne funksjonen er i en util fil, så hovedfilen er mindre rotete allerede. Det er også skrevet I TypeScript i stedet for vanlig JavaScript, så vi har fordelen av typedefinisjoner for å hjelpe oss.
vi konverterer widgetRespDTO s til widget s. selv om forkortet, har vi full kunnskap om hva wResp er. Vi lager en widgetHeader, og en widgetDetail, det er lett å se. Vi forstår også hva oTS og cTS er. Vi kan fortelle WidgetRevisionsRespDTO s er nestet inne i WidgetRespDTO.
Noen veldig vennlig omdøpt innkommende variablene slik at alle som ser denne koden vet hva de er. Til slutt ser vi en Widget må bestå av det returnerte {widgetHeader, widgetDetail, widgetRevisions} objektet, siden det må samsvare med returtypen Widget angitt øverst.
Hvilken kode ville du føle deg bedre om å bruke?
hvem tjener på det?
Godt dokumentert kode fordeler mange mennesker:
Junior utviklere
fordi det er i vanlig språk og lett å forstå, hjelper dokumentasjon junior utviklere og nye teammedlemmer føler seg trygge hoppe inn i en kodebase. Dette forhindrer frustrasjon og tidlig oppgivelse av en oppgave fordi det blir for komplisert for fort.
det er også nyttig for junior utviklere å skrive sin egen dokumentasjon slik at de kan dele koden sin med andre, og slik at de kan få en bedre forståelse av koden sin.
Seniorutviklere
ved å ta deg tid til å dokumentere nå, bruker seniorutviklere mindre tid på å forklare koden sin til andre i fremtiden.
De kan også skrive mer kompleks kode. Vanlig språkdokumentasjon lar andre bruke den som en svart boks, uten å måtte forstå det indre arbeidet.
Lag& åpen kildekode prosjekter
Personalendringer kan gi en enorm nedgang i et prosjekt. Oppdatert og godt dokumentert kode kan tjene som forsikring mot slike forsinkelser og la de gjenværende teammedlemmene ta et skritt tilbake, gjennomgå koden fra et høyt nivå og bestemme seg for det beste handlingsforløpet fremover, og om nødvendig, ombord på nye ansatte.
Du
når du dokumenterer kode, må du oppsummere det. For å oppsummere riktig må du kunne forstå det, og holde de forskjellige delene i hodet samtidig. Å skrive eller bidra til dokumentasjonen er en snarvei for å virkelig forstå en kodebase, gi store bidrag og føle seg som en stor del av et godt lag.
God dokumentasjon KAN TØRKE opp vår kodeopplevelse
som programmerer har du sikkert hørt Om Ikke Gjenta deg selv-prinsippet som en nøkkel til å skrive ren og kortfattet kode. I stedet for å gjenta den samme kodeblokken flere ganger, skriv en funksjon som kan skrives en gang og brukes over hele søknaden din.
på samme måte bør du og teamet ditt ikke løpe inn i lignende problemer og deretter gjenoppfinne hjulet hver gang du prøver å løse dem. For eksempel, har du noen gang hørt en av dine kolleger eller funnet deg selv å si:
«Agh, jeg løste noe som ligner på dette, men jeg husker aldri hvordan jeg gjør det når det kommer opp… Jeg burde skrive det ned et sted.»
du finner deg selv å skanne de samme Stack Overflow-trådene igjen og igjen.
Spar deg selv og dine kolleger denne sorgen ved å følge ÅNDEN I DET TØRRE prinsippet og skrive et dokument som du kan bruke hver gang problemet kommer opp! Dette vil hjelpe deg og andre i teamet ditt med å spare tid, og være mer effektive ved å skrive enklere, mer håndterlig og mer effektiv kode.
hvordan har kodedokumentasjon, eller mangelen på det, påvirket deg?