Kodedokumentasjon :The Complete Beginner’ S Guide
Du er litt måter i din første programmeringsjobb, og ting blir enklere. I begynnelsen kan all koden du måtte håndtere ha overveldet og forvirret deg, men du begynner å få tak i det. Det er flott! Nå lurer du på hvordan du tar koden du skriver til neste nivå. Mens det er mange ting å lære om programmerings stack, hvorav mange vil gjøre deg til en bedre programmerer, er det noen som vil tjene deg uansett hva stabelen du jobber i. En av disse er kodedokumentasjon.
Mange utviklere skriver ikke nok dokumentasjon, enten fordi de ikke ser verdien eller fordi de føler at de ikke har tid. Du trenger ikke å være en av disse utviklerne. Med litt tid og mye øvelse kan du legge til dokumentasjon for koden din som gjør det til en glede å bruke for både deg og alle andre som kommer med.
God Dokumentasjon Kommer I Mange Former
når de fleste utviklere tenker på kodedokumentasjon, tenker de på kommentarer. Kommentarer kan være verdifulle tillegg til kode, men de er ikke den eneste definisjonen av dokumentasjon. Dokumentasjon er alt du skriver i tillegg til koden din for å hjelpe noen andre å forstå hvordan det fungerer. Du kan ikke tenke på det på denne måten, men et godt eksempel på kodedokumentasjon er EN README-fil. Et godt eksempel på grunnleggende dokumentasjon Er Express.js README-fil. Den svarer på flere viktige spørsmål om rammeverket og forteller deg hvordan du kan inkludere det i prosjektet, hvordan du installerer det og hvordan du kjører tester.
God dokumentasjon kan også komme I FORM AV API-dokumentasjon. Igjen, Uttrykk.js gir et godt eksempel. Denne versjonen av dokumentasjonen er mer av et referansebibliotek for utviklere som bruker rammeverket. Du finner svar på spørsmål om hva enkelte funksjoner gjør og hva ulike parametere for disse funksjonene betyr. Uten den kvalitetsdokumentasjonen ville Express ikke ha nesten like mange lag som de gjør.
og selvfølgelig kan du også bruke in-line kommentarer til dokumentkode. Slike kommentarer brukes vanligvis ikke til å lære folk utenfor ditt eget lag om koden. I stedet er de nyttige for å forklare hva som skjer i en bestemt kodebit til lagkameratene dine eller til ditt fremtidige selv.
Hvorfor Du Bør Dokumentere Koden
som nevnt ovenfor, forstår mange utviklere ikke formålet med kodedokumentasjon. De vil hevde at god kode skal være selvdokumenterende, og at du ikke trenger å forklare det. Disse menneskene er i et ord feil. Sannheten er at god dokumentasjon er en viktig del av enhver kodebase. Hvorfor? Fordi folk ikke trenger å lese all koden din for å forstå hva den gjør. “Folk” i den forrige setningen kan referere til noen, inkludert ditt fremtidige selv.
sannheten er at ofte er” folkene ” som trenger å forstå kode etter at den er skrevet, deg. Den lille logikken som virket så smart da du skrev det for seks måneder siden, kan være vanskelig å forstå i dag. Hvis koden din er godt dokumentert, trenger du ikke å bruke tid på å prøve å forstå hva den gjør. Du kan bruke noen sekunder på å se på beskrivelsen og deretter komme tilbake til det du jobber med akkurat nå.
hvis du er heldig nok til å jobbe med kode som brukes av dusinvis eller hundrevis av utviklere, er god dokumentasjon enda viktigere. Brukernes liv vil bli betydelig forbedret av din tid brukt til å skrive god dokumentasjon, og de vil takke deg for det. Bokstavelig talt!
nøkkelen til å huske er at god dokumentasjon sparer mer tid enn det tar å skrive den. Det kan være din tid, eller det kan være tiden for gruppemedlemmer, eller til og med folk du aldri møter. Noen ganger vil skriftlig dokumentasjon til og med hjelpe deg med å gjenkjenne en del av koden din som er for komplisert, slik at du kan forenkle den.
Noen Vanlige Dokumentasjonsfeil
som junior utvikler må du bruke tid på å lære hva som gjør dokumentasjon effektiv. Den gode nyheten er at du kan lære av folk som har gått før deg, slik at du kan unngå vanlige feil.
Underdokumentasjon
en vanlig feil jeg ser med kodedokumentasjon er å dokumentere informasjon som allerede er tydelig synlig. For eksempel vil lat utviklere legge til “dokumentasjon” til en funksjon ved å legge til en blokk som gir navnet på en funksjon, samt navnene på hver parameter og deres individuelle typer. Denne typen dokumentasjon er ubrukelig! Det tar sekunder for noen å lese navnet på funksjonen og parametrene det tar. Det er ikke dokumentasjon, det er bare repetisjon. I stedet bør dokumentasjonen inneholde en rask bit av informasjon om hva funksjonen gjør og hvordan hver parameter endrer funksjonens atferd eller hvorfor det er nødvendig.
Overdokumentasjon
det motsatte mønsteret kan også være et alvorlig problem. For å unngå å skrive for lite dokumentasjon, liker noen utviklere å skrive ut forklaringen på hver liten logikk som finnes i en funksjon. De dokumenterer omhyggelig hver begrunnelse som gikk inn i å skape funksjonen. Når de er ferdige, kan de ha brukt så lenge å skrive funksjonen som de skrev dokumentasjonen. Hva er verre, dokumentasjonen er ofte vanskelig å forstå og tar like lang tid som å lese koden. Den slags dokumentasjon er også bortkastet tid. I stedet gir god dokumentasjon en grunnleggende forklaring på både hva og hvorfor. Hvis det er noen spesielt vanskelige deler av koden å forstå, bør dokumentasjonen bare forklare disse delene.
Avhengig Av Tester For Å Dokumentere
Av og til vil du støte på noen som hevder at den beste form for dokumentasjon er enhetstester. At tilnærmingen har en stor brist: lesing enhet tester er ofte like vanskelig å gjøre som å lese koden selv. Enhver utvikler som ønsker å lære hva koden din gjør, vil ha et stort første skritt mens de jakter og leser alle enhetstestene dine. Mange vil bare gi opp før oppnå hva de satt ut for å gjøre. Mens enhetstesting er et verdifullt tillegg til enhver kodebase, er det ikke en erstatning for god dokumentasjon.
Måter Å Ta Dokumentasjon Til Neste Nivå
hvis du jobber på en stor kodebase, kan kodedokumentasjon føles skremmende, spesielt hvis du ikke har vært flittig med å dokumentere kode opp til dette punktet. Det kan føles som om du prøver å koke havet. Hvis du har en stor kodebase, eller en der du vet at god dokumentasjon er kritisk, vil du kanskje undersøke automatiserte kodedokumentasjonsverktøy. Disse verktøyene drastisk forenkle prosessen med å skrive konsekvent, god dokumentasjon for et helt team. Et verktøy som GhostDoc vil intelligent se på koden din og bruke maler etablert av teamet ditt for å starte dokumentasjonen med et par tastetrykk. Automatiserte dokumentasjonsverktøy fjerner en av de andre vanlige grunnene til å motsette seg skriftlig dokumentasjon: det tar for mye tid.
når du har konsekvent dokumentasjon, kan du enkelt dele den dokumentasjonen med andre verktøy. Automatiserte dokumentasjonsverktøy tar smerten ut av å utvikle god dokumentasjon for ting som offentlige Apier som koden din gir.
Kom I Gang I Dag
Å Skrive god dokumentasjon Er mye enklere enn å skrive kode. I motsetning til kode er dokumentasjon ikke en alt-eller-ingenting-bedrift. Start med et mål å skrive god dokumentasjon for en funksjon hver dag. Den slags praksis bygger sunne vaner, og du vil se utbetalingen nedover veien når du bruker mye mindre tid på å prøve å forstå deler av kodebasen din. Over tid vil det begynne å føle seg feil når du skriver kode som ikke har god dokumentasjon. Du vil begynne å peke ut måter å forbedre dokumentasjonen til dine kolleger under kodegjennomgang. En liten vane vil forbedre lagets kode for hele virksomheten din.
Lær hvordan GhostDoc kan bidra til å forenkle XML-Kommentarer, produsere og vedlikeholde kvalitetshjelpedokumentasjon.
Om forfatteren
Eric Boersma
Eric Boersma er en programvareutvikler og utviklingsleder som har gjort alt FRA IT-sikkerhet i legemidler til å skrive intelligensprogramvare FOR DEN AMERIKANSKE regjeringen til å bygge internasjonale utviklingsteam for ideelle organisasjoner. Han elsker å snakke om ting han har lært underveis, og han liker å lytte til og lære av andre også.
