Hvorfor dokumentation betyder noget, og hvorfor du skal inkludere den i din kode

Der er en overflod af akronymer, når det kommer til softwareudvikling. KISS, TØR, SOLID ... og så videre og så videre. Men når det kommer til at dokumentere eller kommentere din kode, er der ingen enkel slagord.

Hvorfor det?

Dokumentation skal være lige så vigtig for en udvikler som alle andre aspekter af udviklingen

I denne artikel vil jeg argumentere for, at dokumentation af din kode vil føre til at blive en bedre udvikler og vil bidrage til at være et godt teammedlem.

Ingen har tid til det

Hovedårsagskoden går udokumenteret på grund af tid.

Når vi udvikler en funktion, der skal afsluttes inden for en bestemt tidsramme, har vi sjældent et øjeblik til at stoppe alt og fokusere på at dokumentere vores kode.

Bortset fra at designe og skrive selve koden er vi også nødt til at gennemgå kodevurderinger, automatiseringstest og tilføje enhedstest (for at nævne et par ting). Dokumentation er stort set udeladt af ligningen.

Det er den mindst tænkte på detaljer, der kan gøre størst forskel i fremtiden.

Uanset hvad du udvikler, er chancerne for, at du eller en af ​​dine kolleger en dag skal se det igen. Når den dag kommer, vil du ikke huske så levende, hvad du skrev, og hvorfor.

Og hvis du husker, kan der være nogle kanttilfælde eller specifikke anvendelser, som muligvis ikke er tydelige. Den åbenlyse løsning er dokumentation .

At tage den ekstra tid til at skrive en ordentlig beskrivelse af, hvad du har arbejdet med, sparer enorme mængder tid i fremtiden.

Næste gang nogen vil forstå, hvad der sker inden i din kode, skal du blot henvise dem til dokumentationen. Det sparer tid for dig, da du ikke behøver at forklare ting, og det vil spare tid for dem, da de ikke er afhængige af dig.

Og når alt kommer til alt, når du som udvikler har brug for at forstå noget om et bestemt aspekt af kodning, hvad laver du?

? Gå til dokumentationen?

God kode behøver ikke dokumentation

Ja, jeg ved, jeg ved ... velskrevet kode, der er kortfattet og gennemtænkt, behøver ikke at blive dokumenteret. Det læser som en historie .

Selvom det kan være sådan, giver det ikke afkald på behovet for dokumentation, og her er hvorfor:

  1. Vi er alt for fortrolige med robustheden i koden, der indeholder en funktion. Når man ser på et afsnit af koden, gør det måske ikke klart, at der er andre sektioner, der er dybt knyttet til det.
  2. Hver tjeneste, du opretter, har en unik API. At skrive, hvordan man bruger den API, kræver dokumentation, der kan læses uden for koden. Du ønsker ikke at pumpe selve klassen med detaljer om, hvordan du bruger API'en.
  3. Medarbejdere, der arbejder i forskellige afdelinger (som måske ikke er udviklere), vil måske forstå, hvad du gjorde, og hvordan det fungerer.
  4. Bare selve handlingen kan få dig til at se anderledes på den kode, du skrev. At forklare, hvad din kode gør, får dig til at vurdere gyldigheden af ​​den og måske overveje at ændre ting, hvis de ikke lever op til dine forventninger.
  5. Af hensyn til eftertiden

Sådan skriver du god dokumentation

God dokumentation er som en god blok kode. Kort, enkel og let at forstå. Her er et par retningslinjer, du kan følge:

  • Forstå, hvem dokumentationen er rettet mod. Er det kun for udviklere? Er der et bredere publikum? At forstå dette vil spare dig for tid, da du ved på forhånd, hvor meget du skal uddybe i dine forklaringer.
  • Skriv en kort, men beskrivende baggrund, der forklarer hovedpunkterne i det, du byggede. Dette hjælper læsere med at forstå formålet med funktionen og fastslå dens relevans for det, de vil vide.
  • Liste over og beskriv de vigtigste perspektiver for din funktion, og sørg for at påpege eventuelle afhængigheder, der findes med andre funktioner.
  • Sørg for, at der er et tidsstempel, der fortæller læserne, om dokumentationen er gyldig. Også, hvis du bruger visse biblioteker, skal du også medtage deres versioner.
  • Vær generøs med dine kodningseksempler, og detaljer om, hvordan du korrekt bruger den funktion, du skrev, og fremvis de forventede resultater.

Eksempler

For yderligere at forstå, hvordan god dokumentation ser ud, gennemgår vi nogle gode eksempler: Mozillas Developer Network (MDN), Django og Stripe.

I MDN's dokumentation kan du tydeligt se, at hver side starter med en kort forklaring om emnet.

Derefter fortsætter det med at specificere brugssagerne og metoderne. Endelig viser den, hvilke browsere der er kompatible med funktionen og giver links til relevant materiale.

Djangos dokumentation er meget robust. Uanset dit kodningsniveau starter de dig med et overblik og selvstudier.

Derefter gennemgår de hvert emne og beskriver det omhyggeligt og giver korte og koncise kodestykker, der viser, hvad der skal gøres

Jeg håber, jeg har formået at understrege vigtigheden af ​​dokumentation og har givet dig nogle tip til, hvordan du begynder at dokumentere din kode. Hvis du har en idé til et akronym for dokumentation, er du velkommen til at gøre det i kommentarerne nedenfor.

Måske KID - K eep I t D dokumenteret?

Hvis du kunne lide denne artikel, skal du klappe væk, så andre også kan nyde den! ???