Code Documentation: The Complete Beginner’ s Guide
du er lidt ind i dit første programmeringsjob, og tingene bliver lettere. Først kunne al den kode, du havde at gøre med, Have overvældet og forvirret dig, men du begynder at få fat i det. Det er fedt! Nu undrer du dig over, hvordan du tager koden du skriver til næste niveau. Mens der er mange ting at lære om din programmeringsstak, hvoraf mange vil gøre dig til en bedre programmør, er der et par, der tjener dig, uanset hvilken stak du arbejder i. En af dem er kodedokumentation.
mange udviklere skriver ikke nok dokumentation, enten fordi de ikke ser værdien, eller fordi de føler, at de ikke har tid. Du behøver ikke at være en af disse udviklere. Med lidt tid og en masse øvelse kan du tilføje dokumentation til din kode, der gør det til en glæde at læse den til både dig og alle andre, der følger med.
god dokumentation kommer i mange former
når de fleste udviklere tænker på kodedokumentation, tænker de på kommentarer. Kommentarer kan være værdifulde tilføjelser til kode, men de er ikke den eneste definition af dokumentation. Dokumentation er alt, hvad du skriver ud over din kode for at hjælpe en anden med at forstå, hvordan det fungerer. Du tænker måske ikke på det på denne måde, men et godt eksempel på kodedokumentation er en README-fil. Et godt eksempel på grundlæggende dokumentation er udtrykket.js README fil. Det besvarer flere vigtige spørgsmål om rammen og fortæller dig, hvordan du kan inkludere det i dit projekt, hvordan du installerer det, og hvordan du kører test.
god dokumentation kan også komme i form af API-dokumentation. Endnu en gang udtrykke.js er et godt eksempel. Denne version af dokumentation er mere et referencebibliotek for udviklere, der bruger rammen. Du kan finde svar på spørgsmål om, hvad de enkelte funktioner gør, og hvad forskellige parametre til disse funktioner betyder. Uden den kvalitetsdokumentation ville Ekspressen ikke have næsten lige så mange hold, der bruger det som de gør.
og selvfølgelig kan du også bruge In-line kommentarer til at dokumentere kode. Disse slags kommentarer bruges normalt ikke til at lære folk uden for dit eget team om koden. I stedet er de nyttige til at forklare, hvad der sker i en bestemt smule kode til dine holdkammerater eller til dit fremtidige selv.
hvorfor du skal dokumentere din kode
som nævnt ovenfor forstår mange udviklere ikke formålet med kodedokumentation. De vil hævde, at god kode skal være selvdokumenterende, og at du ikke behøver at forklare det. Disse mennesker er i et ord forkert. Sandheden er, at god dokumentation er en væsentlig del af enhver kodebase. Hvorfor? Fordi folk ikke behøver at læse hele din kode for at forstå, hvad den gør. “Mennesker” i den foregående sætning kan henvise til enhver, inklusive dit fremtidige selv.
sandheden er, at ofte er de “mennesker”, der skal forstå koden, efter at den er skrevet, dig. Den lille smule logik, der syntes så smart, da du skrev det for seks måneder siden, kan være svært at forstå i dag. Hvis din kode er veldokumenteret, behøver du ikke bruge tid på at prøve at forstå, hvad den gør. Du kan bruge et par sekunder på at se på beskrivelsen og derefter komme tilbage til det, du arbejder på lige nu.
hvis du er heldig nok til at arbejde på kode, der bruges af snesevis eller hundredvis af udviklere, er god dokumentation endnu vigtigere. Dine brugeres liv vil blive væsentligt forbedret af din tid brugt på at skrive god dokumentation, og de vil takke dig for det. Bogstaveligt talt!
nøglen til at huske er, at god dokumentation sparer mere tid, end det tager at skrive den. Det kan være din tid, eller det kan være tidspunktet for teammedlemmer, eller endda mennesker, du aldrig møder. Nogle gange vil skrivedokumentation endda hjælpe dig med at genkende en del af din kode, der er for kompliceret, så du kan forenkle den.
nogle almindelige Dokumentationsfejl
som juniorudvikler skal du bruge tid på at lære, hvad der gør dokumentationen effektiv. Den gode nyhed er, at du kan lære af folk, der har gået før dig, så du kan undgå almindelige fejl.
under-dokumentation
en almindelig fejl, jeg ser med kodedokumentation, er at dokumentere oplysninger, der allerede er tydeligt synlige. For eksempel vil dovne udviklere tilføje “dokumentation” til en funktion ved at tilføje en blok, der giver navnet på en funktion samt navnene på hver parameter og deres individuelle typer. Denne type dokumentation er ubrugelig! Det tager sekunder for nogen at læse navnet på funktionen og de parametre, det tager. Det er ikke dokumentation, det er bare gentagelse. I stedet skal dokumentationen indeholde en hurtig smule information om, hvad funktionen gør, og hvordan hver parameter ændrer funktionens adfærd, eller hvorfor det er nødvendigt.
Overdokumentation
det modsatte mønster kan også være et alvorligt problem. For at undgå at skrive for lidt dokumentation, kan nogle udviklere gerne skrive forklaringen på hver lille smule logik, der er indeholdt i en funktion. De dokumenterer omhyggeligt alle begrundelser, der gik i at skabe funktionen. Når de er færdige, har de måske brugt så lang tid på at skrive funktionen, som de skrev dokumentationen. Hvad værre er, dokumentationen er ofte vanskelig at forstå og tager lige så lang tid som at læse koden. Den slags dokumentation er også spild af tid. I stedet giver god dokumentation en grundlæggende forklaring på både hvad og hvorfor. Hvis der er nogen særlig vanskelige dele af koden at forstå, skal dokumentationen forklare netop disse dele.
afhængig af test til dokument
lejlighedsvis løber du på tværs af nogen, der hævder, at den bedste form for dokumentation er enhedstest. Denne tilgang har en stor mangel: test af læseenheder er ofte lige så vanskelige at gøre som selve læsekoden. Enhver udvikler, der ønsker at lære, hvad din kode gør, vil have et stort første skridt, mens de jager og læser alle dine enhedstest. Mange vil bare give op, før de opnår det, de har til hensigt at gøre. Mens enhedstest er en værdifuld tilføjelse til enhver kodebase, er det ikke en erstatning for god dokumentation.
måder at tage dokumentation til næste niveau
hvis du arbejder på en stor kodebase, kan kodedokumentation føles skræmmende, især hvis du ikke har været flittig med at dokumentere kode op til dette punkt. Det kan føles som om du prøver at koge havet. Hvis du har en stor kodebase, eller en, hvor du ved, at god dokumentation er kritisk, kan du undersøge automatiserede kodedokumentationsværktøjer. Disse værktøjer forenkler processen med at skrive konsekvent, god dokumentation for et helt team drastisk. Et værktøj som GhostDoc vil intelligent se på din kode og bruge skabeloner etableret af dit team til at kickstarte din dokumentation med et par tastetryk. Automatiserede dokumentationsværktøjer fjerner en af de andre almindelige grunde til at modsætte sig skrivedokumentation: det tager for meget tid.
når du har konsistent dokumentation, giver andre værktøjer dig mulighed for nemt at dele denne dokumentation. Automatiserede dokumentationsværktøjer tager smerten ud af at udvikle god dokumentation til ting som offentlige API ‘ er, som din kode giver.
kom i gang i dag
at skrive god dokumentation er meget lettere end at skrive kode. I modsætning til kode er dokumentation ikke en alt-eller-intet-virksomhed. Start med et mål om at skrive god dokumentation for en funktion hver dag. Den slags praksis bygger sunde vaner, og du vil se udbetalingen ned ad vejen, når du bruger meget mindre tid på at prøve at forstå dele af din kodebase. Over tid vil det begynde at føle sig forkert, når du skriver kode, der ikke har god dokumentation. Du begynder at påpege måder at forbedre dokumentationen til dine kolleger under kodeanmeldelse. En lille vane vil forbedre dit teams kode for hele din virksomhed.
Lær, hvordan GhostDoc kan hjælpe med at forenkle dine kommentarer, producere og vedligeholde kvalitetshjælpsdokumentation.
om forfatteren
Eric Boersma
Eric Boersma er en programudvikler og udviklingschef, der har gjort alt fra IT-sikkerhed inden for lægemidler til skrivning af efterretningsprogrammer til den amerikanske regering til opbygning af internationale udviklingshold for non-profit. Han elsker at tale om de ting, han har lært undervejs, og han nyder også at lytte til og lære af andre.
