Kodedokumentation er samlingen af letforståelige billeder og skriftlige beskrivelser, der forklarer, hvad en kodebase gør, og hvordan den kan bruges.
det kan være enkle forklarende kommentarer over funktioner og blokke eller en fuldgyldig udviklerhåndbog, komplet med receptpligtig stil dos-and-don ‘ ts, oversigter over hver del af applikationen og tilgange til de mest almindelige typer kodningsopgaver.
det er ofte bedst at finde et lykkeligt medium mellem disse to ekstremer, når du tager den bevidste beslutning om at kommentere din kode og skitsere de gnarlier områder i en kodebase på almindeligt sprog.
hvorfor dokumentere din kode?
hvorfor gå i problemer med at skrive om din kode i stedet for bare at skrive kode? Ville det ikke være mere produktivt alligevel?
Mental Save Points
dokumentation er som et mentalt sparepunkt for de tidspunkter, hvor du endelig får det, der foregår i slutningen af dagen og ikke ønsker at miste momentum. Veldokumenteret kode sikrer, at når du skal dykke tilbage i morgen formiddag (eller flere måneder fra nu), behøver du ikke tage så meget tid på at komme op i fart.
dokumenteret kode bliver genbrugt
forskellen mellem et brugt bibliotek og et ubrugt bibliotek kommer ofte ned til dets dokumentation.
Hvem ønsker at bruge et udokumenteret open source-bibliotek eller bidrage til et udokumenteret projekt? Næsten ingen.
i de fleste tilfælde vil du hellere bruge et mindre kraftfuldt bibliotek, der har dokumenter. Hvorfor? Fordi dokumentationen formidler andre informationspunkter om en kodebase. Udviklerne mener, at projektet er værd at bruge tid og energi på at skrive om det på almindeligt sprog, så enhver, der måtte være interesseret, hurtigt kan komme i gang og lære, hvordan det fungerer, og hvorfor vigtige beslutninger blev taget.
at finde et nyt, interessant og veldokumenteret projekt på dit yndlingssprog kan være meget spændende og sjovt. Lad os se på det ekstreme alternativ: at være forpligtet til at bruge et udokumenteret kodebibliotek og potentielt bidrage til en tilsyneladende bysantinsk kodebase… det lyder ret smertefuldt, ikke?
så hvorfor har du ikke dokumenteret din egen kode?
dokumentation af kode er en del af at skrive god kode
en hjørnesten i god kode er vedligeholdelighed, opnået gennem forståelig, læselig dokumentation.
der er flere måder at dokumentere kode på:
- valg af gode navne til variabler og funktioner
- efterlader korte kommentarer inden for koden for at hjælpe med at give kontekst til fremtidige læsere
- tilføjelse af illustrative billeder såsom sekvens-og enhedsrelationsdiagrammer
- tilvejebringelse af API-dokumenter, der beskriver hver klasse, metode, argument og returværdi
- ved hjælp af et statisk skrevet sprog, såsom TypeScript (TypeScript) typer som dokumentation)
Sammenlign to eksempler
lad os sige, at du får nogle data fra en backend API og” indtager ” det – konvertere det til en mere nyttig form for en front-end UI. Her er den første af 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 }}ovenstående kode har potentialet til at være smertefuldt. Du kan se ved navnet, at dette er en slags konverter, der tager w som sin param.
det ser ud til, at det returnerer en overskrift, måske detaljer og noget, der hedder revs. Hvor kom revs fra, alligevel? Selvfølgelig er der ingen detaljer om de indkommende variabelnavne note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS… eller er der? Er rr forkortelse for returned rev? Hvem kan sige.
lad os se på det andet eksempel.
// 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, }}hvor anderledes! Denne funktion er i en util fil, så hovedfilen er allerede mindre rodet. Det er også skrevet i TypeScript i stedet for almindelig JavaScript, så vi har fordelen ved typedefintioner til at hjælpe os.
vi konverterer widgetRespDTOs til widget s. selvom forkortet, har vi fuld viden om, hvad wResp er. Vi opretter en widgetHeader og en widgetDetail, det er let at se. Vi forstår også, hvad oTS og cTS er. Vi kan fortælle WidgetRevisionsRespDTO s er indlejret inde i WidgetRespDTO.
nogen omdøbte meget venligt de indkommende variabler, så alle, der ser denne kode, ved, hvad de er. Endelig ser vi et Widget skal være sammensat af det returnerede {widgetHeader, widgetDetail, widgetRevisions} objekt, da det skal matche returtypen Widget angivet øverst.
hvilken kode ville du have det bedre med at bruge?
hvem gavner?
veldokumenteret kode gavner mange mennesker:
Junior udviklere
fordi det er i almindeligt sprog og let at forstå, dokumentation hjælper junior udviklere og nye teammedlemmer føler sig trygge hoppe ind i en kodebase. Dette forhindrer frustration og tidlig opgivelse af en opgave, fordi det bliver for kompliceret for hurtigt.
det er også nyttigt for juniorudviklere at skrive deres egen dokumentation, så de kan dele deres kode med andre, og så de kan få en bedre forståelse af deres kode.
seniorudviklere
ved at tage sig tid til at dokumentere nu bruger senior devs mindre tid på at forklare deres kode til andre i fremtiden.
de kan også skrive mere kompleks kode. Almindeligt sprog dokumentation lader andre bruge det som en sort boks, uden at skulle forstå de indre funktioner.
Teams& open source-projekter
personaleændringer kan bringe en enorm afmatning til et projekt. Opdateret og veldokumenteret kode kan tjene som forsikring mod sådanne afmatninger og give de resterende teammedlemmer mulighed for at tage et skridt tilbage, gennemgå koden fra et højt niveau og beslutte den bedste fremgangsmåde fremad, og om nødvendigt, ombord nye medarbejdere.
du
når du dokumenterer kode, skal du opsummere den. For at opsummere korrekt skal du være i stand til at forstå det og holde de forskellige dele i dit hoved på samme tid. At skrive eller bidrage til dokumentationen er en genvej til virkelig at forstå en kodebase, yde enorme bidrag og føle sig som en stor del af et godt team.
god dokumentation kan tørre vores kodningsoplevelse
som programmør har du sikkert hørt om princippet om ikke at gentage dig selv som en nøgle til at skrive ren og kortfattet kode. I stedet for at gentage den samme kodeblok flere gange, skal du skrive en funktion, der kan skrives en gang og anvendes over hele din ansøgning.
på samme måde bør du og dit team ikke løbe ind i lignende problemer og derefter genopfinde hjulet hver gang du forsøger at løse dem. Har du for eksempel nogensinde hørt en af dine kolleger eller fundet dig selv at sige:
“Agh, jeg løste noget, der ligner dette, men jeg kan aldrig huske, hvordan jeg gør det, når det kommer op… Jeg burde nok skrive det ned et sted, ikke?”
du finder dig selv i at scanne de samme Stakoverløbstråde igen og igen.
Spar dig selv og dine kolleger denne sorg ved at følge Ånden i det tørre princip og skrive et dokument, som du kan anvende hver gang problemet kommer op! Dette vil hjælpe dig og andre på dit team med at spare tid og være mere effektive til at skrive enklere, mere håndterbar og mere effektiv kode.
Hvordan har kodedokumentation eller manglen deraf påvirket dig?