Hvordan dokumentere Python-kode ved hjelp av Docstrings

Uten skikkelig dokumentasjon kan det være vanskelig å forstå, vedlikeholde og feilsøke koden din. I Python kan du bruke docstrings for å gi kortfattede beskrivelser og eksempler på hvordan koden fungerer.

Hva er Docstrings?

Docstrings er strenger du kan legge til i Python-koden din for å forklare hva den gjør og hvordan du bruker den. Kodebiten kan være en Python funksjon, en modul eller en klasse.

Docstrings ligner mye på standard Python-kommentarer, men de har noen forskjeller. Python-kommentarer gir tilleggsinformasjon til utviklere om kodens indre virkemåte, for eksempel implementeringsdetaljer eller forbehold du må huske på når du utvider koden.

På den annen side gir docstrings for det meste informasjon til brukere av koden som kanskje ikke nødvendigvis trenger å vite implementeringsdetaljene, men som trenger å forstå hva den gjør og hvordan de skal bruke den.

Hvordan skrive docstrings

Du inkluderer vanligvis docstrings i begynnelsen av kodeblokken du vil dokumentere. Du må legge dem inn i tre anførselstegn (). Du kan skrive en-linje docstrings eller multi-line docstrings.

En-linjes docstrings er egnet for enkel kode som ikke krever mye dokumentasjon.

Nedenfor er et eksempel på en funksjon kalt multiplisere. Dokstringen forklarer at multipliser-funksjonen tar to tall, multipliserer dem og returnerer resultatet.

defmultiplisere(a, b):
Multipliser to tall og returnerer resultatet
komme tilbake a * b

Bruk flerlinjede dokumentstrenger for mer kompleks kode som trenger detaljert dokumentasjon.

Tenk på følgende bilklasse:

klasseBil:

 EN klasserepresentererenbilgjenstand.
 Attributter:
 kjørelengde (flyte): Bilens nåværende kjørelengde.
 Metoder:
 drive (miles): Kjører bilen til det angitte antall miles.

def__i det__(selv, kjørelengde):
 self.mileage = kilometerstand
defkjøre(selv, miles):

 kjører bilen til det angitte antall miles.
 Args:
 miles (flyte): Antall miles å kjøre.
 Returnerer:
Ingen

 self.mileage += miles

Dokstringen for klassen ovenfor beskriver hva klassen representerer, dens attributter og metodene. I mellomtiden gir docstringene for stasjonsmetoden informasjon om hva metoden gjør, argumentene den forventer og hva den returnerer.

Dette gjør det lettere for alle som jobber med denne klassen å forstå hvordan de skal bruke den. De andre fordelene med å bruke docstrings inkluderer:

• Kodevedlikeholdbarhet: Ved å gi en klar beskrivelse av hvordan koden fungerer, hjelper docstrings utviklere med å endre og oppdatere koden uten å introdusere feil.
• Enklere samarbeid: Når flere utviklere samarbeider om samme kodebase – for eksempel med Visual Studio live share-verktøy— docstrings lar utviklere dokumentere koden konsekvent slik at alle i teamet kan forstå den.
• Forbedret kodelesbarhet: Docstrings gir en oppsummering på høyt nivå av hva koden gjør som tillater alle som leser koden for raskt å forstå formålet uten å gå gjennom hele koden blokkere.

Docstring-formater

En god docstring bør beskrive hva et stykke kode gjør, argumentene det forventer, og implementeringsdetaljer om nødvendig. Den bør spesielt inkludere eventuelle edge-tilfeller alle som bruker koden bør være klar over.

Et grunnleggende docstring-format har følgende seksjoner:

• Sammendragslinje: En enlinjes oppsummering av hva koden gjør.
• Argumenter: Informasjon om argumentene funksjonen forventer, inkludert deres datatyper.
• Returverdi: Informasjon om returverdien til funksjonen inkludert dens datatype.
• Høyninger (valgfritt): Informasjon om eventuelle unntak funksjonen kan gi.

Dette er bare et grunnleggende format da det er andre formater du kan velge for å basere dokumentstrengene dine. De mest populære er Epytext, reStructuredText (også kjent som reST), NumPy og Google docstrings. Hvert av disse formatene har sin egen syntaks som vist i følgende eksempler:

Epytekst

En docstring som følger Epytext-formatet:

defmultiplisere(a, b):

 Multipliser to tall sammen.
 @param a: Det første tallet som skal multipliseres.
 @type a: int
 @param b: Det andre tallet som skal multipliseres.
 @type b: int
 @return: Produktet av de to tallene.
 @rtype: int

komme tilbake a * b

reStructuredText (reST)

En docstring som følger reST-formatet:

defmultiplisere(a, b):

 Multipliser to tall sammen.
 :param a: Det første tallet som skal multipliseres.
 :type a: int
 :param b: Det andre tallet som skal multipliseres.
 :type b: int
 :komme tilbake: Produktet av de to tallene.
 :rtype: int

komme tilbake a * b

NumPy

En docstring som følger NumPy-formatet:

defmultiplisere(a, b):

 Multipliser to tall sammen.
 Parametere

 a: int
 Det første tallet som skal multipliseres.
 b: int
 Det andre tallet å multiplisere.
 Returnerer

 int
 Produktet av de to tallene.

komme tilbake a * b

Google

En docstring som følger Google-formatet:

defmultiplisere(a, b):

 Multipliser to tall sammen.
 Args:
 a (int): Det første tallet som skal multipliseres.
 b (int): Det andre tallet som skal multipliseres.
 Returnerer:
 int: Produktet av de to tallene.

komme tilbake a * b

Selv om alle fire docstring-formatene gir nyttig dokumentasjon for multiplikasjonsfunksjonen, er NumPy- og Google-formatene lettere å lese enn Epytext- og reST-formatene.

Hvordan inkludere tester i Docstrings

Du kan inkludere testeksempler i docstringene dine ved å bruke doctest-modulen. Doktestmodulen søker i dokumentstrengen etter tekst som ser ut som interaktive Python-økter, og kjører dem deretter for å bekrefte at de fungerer som de skal.

For å bruke doctests, inkluderer eksempelinndataene og forventede utgangene i docstringen. Nedenfor er et eksempel på hvordan du kan gjøre det:

defmultiplisere(a, b):

 Multipliser to tall sammen.
 Parametere

 a: int
 Det første tallet som skal multipliseres.
 b: int
 Det andre tallet å multiplisere.
 Returnerer

 int
 Produktet av de to tallene.
 Eksempler

 >>> multipliser(2, 3)
6
 >>> multipliser(0, 10)
0
 >>> multipliser(-1, 5)
-5

komme tilbake a * b

De Eksempler seksjonen inneholder tre funksjonskall med forskjellige argumenter og spesifiserer forventet utgang for hver. Når du kjører doctest-modulen som vist nedenfor, vil den utføre eksemplene og sammenligne den faktiske utgangen med den forventede utgangen.

python -m doctest multiply.py

Hvis det er noen forskjeller, rapporterer doctest-modulen dem som feil. Å bruke doctests med docstrings som dette hjelper deg å bekrefte at koden fungerer som forventet. Vær oppmerksom på at doktester ikke er en erstatning for mer omfattende enhetstester og integrasjonstester for Python-koden din.

Hvordan generere dokumentasjon fra Docstrings

Du har lært det grunnleggende om bruk av docstrings for å dokumentere Python-koden og viktigheten av dokumentasjon av høy kvalitet. For å ta det opp et hakk, kan det være lurt å generere dokumentasjon for modulene og funksjonene dine fra deres respektive docstrings.

En av de mest populære dokumentasjonsgeneratorene du kan bruke er Sphinx. Den støtter reST docstring-format som standard, men du kan konfigurere den til å fungere med Google- eller NumPy-formatet.