Kako dokumentirati Python kod pomoću nizova dokumenata

Bez odgovarajuće dokumentacije može biti teško razumjeti, održavati i otklanjati pogreške u vašem kodu. U Pythonu možete koristiti nizove dokumenata za pružanje sažetih opisa i primjera kako kod funkcionira.

Što su nizovi dokumenata?

Docstrings su nizovi koje možete dodati svom Python kodu da biste objasnili što radi i kako ga koristiti. Dio koda može biti a Python funkcija, modul ili klasa.

Nizovi dokumenata uvelike nalikuju standardnim Python komentarima, ali imaju neke razlike. Python komentari pružaju dodatne informacije programerima o unutarnjem funkcioniranju koda, kao što su detalji implementacije ili upozorenja koja treba imati na umu prilikom proširenja koda.

S druge strane, nizovi dokumenata uglavnom pružaju informacije korisnicima koda koji možda ne moraju nužno znati detalje njegove implementacije, ali trebaju razumjeti što on radi i kako ga koristiti.

Kako pisati nizove dokumenata

Obično uključujete nizove dokumenata na početku bloka koda koji želite dokumentirati. Morate ih staviti u trostruke navodnike (). Možete pisati nizove dokumenata u jednom redu ili nizove dokumenata u više redaka.

Nizovi dokumenata u jednom retku prikladni su za jednostavan kod koji ne zahtijeva puno dokumentacije.

Ispod je primjer funkcije koja se zove množenje. Niz dokumenata objašnjava kako funkcija množenja uzima dva broja, množi ih i vraća rezultat.

defpomnožiti(a, b):
Množi dva broja i vraća rezultat
povratak a * b

Koristite nizove dokumenata s više redaka za složeniji kod koji treba detaljnu dokumentaciju.

Razmotrite sljedeću klasu automobila:

razredaAutomobil:

 A razredapredstavljanjeaautomobilobjekt.
 Atributi:
 kilometraža (float): trenutna kilometraža automobila.
 Metode:
 vožnja (milje): Vozi auto za navedeni broj milja.

def__u tome__(sam, kilometraža):
 sam.kilometraža = kilometraža
defvoziti(ja, milje):

 Vozi auto za navedeni broj milja.
 Argumenti:
 milje (float): broj milja za vožnju.
 Povratak:
Nijedan

 sam.kilometraža += milja

Niz dokumenata za gornju klasu opisuje što klasa predstavlja, njezine atribute i metode. U međuvremenu, nizovi dokumenata za pogonsku metodu pružaju informacije o tome što metoda radi, argumente koje očekuje i što vraća.

To olakšava svima koji rade s ovom klasom da razumiju kako je koristiti. Druge prednosti korištenja nizova dokumenata uključuju:

• Mogućnost održavanja koda: pružajući jasan opis kako kod radi, nizovi dokumenata pomažu programerima da modificiraju i ažuriraju kod bez unošenja pogrešaka.
• Lakša suradnja: kada nekoliko programera surađuje na istoj bazi koda—na primjer, s Alat za dijeljenje uživo Visual Studio—stringovi dokumenata omogućuju programerima dosljedno dokumentiranje koda tako da ga svi u timu mogu razumjeti.
• Poboljšana čitljivost koda: Docstrings pružaju sažetak visoke razine onoga što kod radi što dopušta svatko tko čita kod kako bi brzo razumio njegovu svrhu bez prolaska kroz cijeli kod blok.

Docstring formati

Dobar niz dokumenata trebao bi opisati što dio koda radi, argumente koje očekuje i detalje implementacije ako je potrebno. Posebno bi trebao uključivati ​​sve rubne slučajeve kojih bi svatko tko koristi kod trebao biti svjestan.

Osnovni format niza dokumenata ima sljedeće odjeljke:

• Redak sažetka: sažetak u jednom retku onoga što kod radi.
• Argumenti: Informacije o argumentima koje funkcija očekuje uključujući njihove vrste podataka.
• Povratna vrijednost: Informacije o povratnoj vrijednosti funkcije uključujući njen tip podataka.
• Povećanja (neobavezno): Informacije o iznimkama koje funkcija može pokrenuti.

Ovo je samo osnovni format budući da postoje i drugi formati koje možete odabrati kao temelj svojih nizova dokumenata. Najpopularniji su Epytext, reStructuredText (poznat i kao reST), NumPy i Google docstrings. Svaki od ovih formata ima vlastitu sintaksu kao što je prikazano u sljedećim primjerima:

Epytext

Niz dokumenata koji slijedi Epytext format:

defpomnožiti(a, b):

 Pomnožite dva broja.
 @param a: Prvi broj za množenje.
 @upišite a: int
 @param b: drugi broj za množenje.
 @tip b: int
 @return: umnožak dvaju brojeva.
 @rtype: int

povratak a * b

restrukturirani tekst (reST)

Niz dokumenata koji slijedi reST format:

defpomnožiti(a, b):

 Pomnožite dva broja.
 :param a: Prvi broj za množenje.
 :tip a: int
 :param b: Drugi broj za množenje.
 :tip b: int
 :povratak: Umnožak dvaju brojeva.
 :rtype: int

povratak a * b

NumPy

Niz dokumenata koji slijedi NumPy format:

defpomnožiti(a, b):

 Pomnožite dva broja.
 Parametri

 a: int
 Prvi broj za množenje.
 b: int
 Drugi broj za množenje.
 Povratak

 int
 Umnožak dvaju brojeva.

povratak a * b

Google

Niz dokumenata koji slijedi Googleov format:

defpomnožiti(a, b):

 Pomnožite dva broja.
 Argumenti:
 a (int): Prvi broj za množenje.
 b (int): drugi broj za množenje.
 Povratak:
 int: umnožak dvaju brojeva.

povratak a * b

Iako sva četiri formata stringa dokumenata pružaju korisnu dokumentaciju za funkciju množenja, formate NumPy i Google lakše je čitati od formata Epytext i reST.

Kako uključiti testove u nizove dokumenata

Možete uključiti primjere testiranja u svoje nizove dokumenata pomoću modula doctest. Modul doctest pretražuje docstring u potrazi za tekstom koji izgleda kao interaktivne Python sesije i zatim ih izvršava kako bi potvrdio da rade kako treba.

Da biste koristili doctestove, uključite ogledne ulaze i očekivane izlaze u niz dokumenata. U nastavku je primjer kako biste to učinili:

defpomnožiti(a, b):

 Pomnožite dva broja.
 Parametri

 a: int
 Prvi broj za množenje.
 b: int
 Drugi broj za množenje.
 Povratak

 int
 Umnožak dvaju brojeva.
 Primjeri

 >>> pomnoži(2, 3)
6
 >>> pomnoži(0, 10)
0
 >>> pomnoži(-1, 5)
-5

povratak a * b

The Primjeri odjeljak sadrži tri poziva funkcija s različitim argumentima i specificira očekivani izlaz za svaki. Kada pokrenete modul doctest kao što je prikazano u nastavku, on će izvršiti primjere i usporediti stvarni izlaz s očekivanim rezultatom.

python -m doctest multiply.py

Ako postoje bilo kakve razlike, modul doctest ih prijavljuje kao greške. Korištenje doctestova s ​​ovakvim nizovima dokumenata pomaže vam da provjerite radi li kod prema očekivanjima. Imajte na umu da doctestovi nisu zamjena za opsežnije jedinične testove i testove integracije za vaš Python kod.

Kako generirati dokumentaciju iz nizova dokumenata

Naučili ste osnove korištenja nizova dokumenata za dokumentiranje vašeg Python koda i važnost visokokvalitetne dokumentacije. Da biste podigli korak dalje, možda ćete htjeti generirati dokumentaciju za svoje module i funkcije iz njihovih odgovarajućih nizova dokumenata.

Jedan od najpopularnijih generatora dokumentacije koji možete koristiti je Sphinx. Podržava reST docstring format prema zadanim postavkama, ali ga možete konfigurirati da radi s Google ili NumPy formatom.