Sådan dokumenterer du Python-kode ved hjælp af Docstrings

Uden ordentlig dokumentation kan det være svært at forstå, vedligeholde og fejlsøge din kode. I Python kan du bruge docstrings til at give kortfattede beskrivelser og eksempler på, hvordan koden fungerer.

Hvad er Docstrings?

Docstrings er strenge, du kan tilføje til din Python-kode for at forklare, hvad den gør, og hvordan du bruger den. Kodestykket kan være en Python funktion, et modul eller en klasse.

Docstrings ligner meget standard Python-kommentarer, men de har nogle forskelle. Python-kommentarer giver udviklere yderligere information om kodens indre funktion, såsom implementeringsdetaljer eller advarsler, der skal huskes, når koden udvides.

På den anden side giver docstrings for det meste information til brugere af koden, som måske ikke nødvendigvis har brug for at kende dens implementeringsdetaljer, men har brug for at forstå, hvad den gør, og hvordan man bruger den.

Sådan skriver du docstrings

Du inkluderer typisk docstrings i begyndelsen af ​​den kodeblok, du vil dokumentere. Du skal angive dem i tredobbelte anførselstegn (). Du kan skrive en-linje docstrings eller multi-line docstrings.

One-line docstrings er velegnede til simpel kode, der ikke kræver meget dokumentation.

Nedenfor er et eksempel på en funktion kaldet multiplicere. Docstringen forklarer, at multiplikationsfunktionen tager to tal, multiplicerer dem og returnerer resultatet.

defformere sig(a, b):
Multiplicerer to tal og returnerer resultatet
Vend tilbage a * b

Brug multi-line docstrings til mere kompleks kode, der kræver detaljeret dokumentation.

Overvej følgende bilklasse:

klasseBil:

 EN klasserepræsenterer-enbilobjekt.
 Egenskaber:
 kilometertal (float): Bilens aktuelle kilometertal.
 Metoder:
 drive (miles): Kører bilen til det angivne antal miles.

def__i det__(selv, kilometertal):
 self.mileage = kilometertal
defkøre(selv, miles):

 Kører bilen til det angivne antal miles.
 Args:
 miles (float): Antallet af miles, der skal køres.
 Vender tilbage:
Ingen

 selv.kilometertal += miles

Docstringen for ovenstående klasse beskriver, hvad klassen repræsenterer, dens attributter og dens metoder. I mellemtiden giver docstrings for drevmetoden information om, hvad metoden gør, de argumenter, den forventer, og hvad den returnerer.

Dette gør det nemmere for alle, der arbejder med denne klasse, at forstå, hvordan man bruger den. De andre fordele ved at bruge docstrings inkluderer:

• Kodevedligeholdelse: Ved at give en klar beskrivelse af, hvordan koden fungerer, hjælper docstrings udviklere med at ændre og opdatere koden uden at introducere fejl.
• Nemmere samarbejde: Når flere udviklere samarbejder på den samme kodebase – for eksempel med Visual Studio live share værktøj— docstrings giver udviklere mulighed for at dokumentere koden konsekvent, så alle i teamet kan forstå den.
• Forbedret kodelæsbarhed: Docstrings giver en oversigt på højt niveau af, hvad kode gør, hvilket tillader enhver, der læser koden for hurtigt at forstå dens formål uden at gennemgå hele koden blok.

Docstring-formater

En god docstring bør beskrive, hvad et stykke kode gør, de argumenter, det forventer, og implementeringsdetaljer, hvis det er nødvendigt. Det bør især inkludere eventuelle edge-tilfælde, som alle, der bruger koden, bør være opmærksomme på.

Et grundlæggende docstring-format har følgende sektioner:

• Opsummeringslinje: En oversigt på én linje af, hvad koden gør.
• Argumenter: Oplysninger om de argumenter, som funktionen forventer, inklusive deres datatyper.
• Returværdi: Oplysninger om funktionens returværdi inklusive dens datatype.
• Forhøjelser (valgfrit): Oplysninger om eventuelle undtagelser, som funktionen kan rejse.

Dette er blot et grundlæggende format, da der er andre formater, du kan vælge til at basere dine docstrings på. De mest populære er Epytext, reStructuredText (også kendt som reST), NumPy og Google docstrings. Hvert af disse formater har sin egen syntaks som vist i følgende eksempler:

Epytekst

En docstring, der følger Epytext-formatet:

defformere sig(a, b):

 Gang to tal sammen.
 @param a: Det første tal, der skal ganges.
 @type a: int
 @param b: Det andet tal, der skal ganges.
 @type b: int
 @return: Produktet af de to tal.
 @rtype: int

Vend tilbage a * b

reStructuredText (reST)

En docstring, der følger reST-formatet:

defformere sig(a, b):

 Gang to tal sammen.
 :param a: Det første tal, der skal ganges.
 :type a: int
 :param b: Det andet tal, der skal ganges.
 :type b: int
 :Vend tilbage: Produktet af de to tal.
 :rtype: int

Vend tilbage a * b

NumPy

En docstring, der følger NumPy-formatet:

defformere sig(a, b):

 Gang to tal sammen.
 Parametre

 a: int
 Det første tal, der skal ganges.
 b: int
 Det andet tal at gange.
 Vender tilbage

 int
 Produktet af de to tal.

Vend tilbage a * b

Google

En docstring, der følger Google-formatet:

defformere sig(a, b):

 Gang to tal sammen.
 Args:
 a (int): Det første tal, der skal ganges.
 b (int): Det andet tal, der skal ganges.
 Vender tilbage:
 int: Produktet af de to tal.

Vend tilbage a * b

Selvom alle fire docstring-formater giver nyttig dokumentation for multiplikationsfunktionen, er NumPy- og Google-formaterne lettere at læse end Epytext- og reST-formaterne.

Sådan inkluderes tests i Docstrings

Du kan inkludere testeksempler i dine docstrings ved hjælp af doctest-modulet. Doktestmodulet søger i docstringen efter tekst, der ligner interaktive Python-sessioner, og udfører dem derefter for at bekræfte, at de fungerer, som de skal.

For at bruge doctests skal du inkludere eksempelinput og forventede output i docstringen. Nedenfor er et eksempel på, hvordan du ville gøre det:

defformere sig(a, b):

 Gang to tal sammen.
 Parametre

 a: int
 Det første tal, der skal ganges.
 b: int
 Det andet tal at gange.
 Vender tilbage

 int
 Produktet af de to tal.
 Eksempler

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

Vend tilbage a * b

Det Eksempler sektionen indeholder tre funktionskald med forskellige argumenter og specificerer det forventede output for hver. Når du kører doctest-modulet som vist nedenfor, vil det udføre eksemplerne og sammenligne det faktiske output med det forventede output.

python -m doctest multiply.py

Hvis der er forskelle, rapporterer doctest-modulet dem som fejl. Brug af doctests med docstrings som denne hjælper dig med at bekræfte, at koden fungerer som forventet. Bemærk, at doctests ikke er en erstatning for mere omfattende enhedstest og integrationstest til din Python-kode.

Sådan genereres dokumentation fra Docstrings

Du har lært det grundlæggende i at bruge docstrings til at dokumentere din Python-kode og vigtigheden af ​​dokumentation af høj kvalitet. For at tage det op, vil du måske generere dokumentation for dine moduler og funktioner fra deres respektive docstrings.

En af de mest populære dokumentationsgeneratorer, du kan bruge, er Sphinx. Det understøtter reST docstring-format som standard, men du kan konfigurere det til at arbejde med Google- eller NumPy-formatet.