Kako dokumentirati kodo Python z uporabo nizov dokumentov

Brez ustrezne dokumentacije je lahko težko razumeti, vzdrževati in odpravljati napake v vaši kodi. V Pythonu lahko uporabite nize dokumentov za jedrnate opise in primere delovanja kode.

Kaj so nizi dokumentov?

Docstrings so nizi, ki jih lahko dodate svoji kodi Python, da pojasnite, kaj počne in kako jo uporabljati. Del kode je lahko a Funkcija Python, modul ali razred.

Nizi dokumentov so zelo podobni standardnim komentarjem Python, vendar imajo nekaj razlik. Komentarji Python nudijo razvijalcem dodatne informacije o notranjem delovanju kode, kot so podrobnosti o implementaciji ali opozorila, ki jih je treba upoštevati pri razširitvi kode.

Po drugi strani nizi dokumentov večinoma zagotavljajo informacije uporabnikom kode, ki jim ni nujno, da poznajo podrobnosti njene implementacije, vendar morajo razumeti, kaj počne in kako jo uporabljati.

Kako napisati nize dokumentov

Nize dokumentov običajno vključite na začetek bloka kode, ki ga želite dokumentirati. Morate jih dati v trojne narekovaje (). Napišete lahko enovrstične dokumentne nize ali večvrstične dokumentne nize.

Enovrstični nizi dokumentov so primerni za preprosto kodo, ki ne zahteva veliko dokumentacije.

Spodaj je primer funkcije, imenovane množenje. Niz dokumenta pojasnjuje, da funkcija množenja vzame dve števili, ju pomnoži in vrne rezultat.

defpomnožiti(a, b):
Pomnoži dve števili in vrne rezultat
vrnitev a * b

Uporabite večvrstične dokumentne nize za bolj zapleteno kodo, ki potrebuje podrobno dokumentacijo.

Razmislite o naslednjem razredu avtomobila:

razredavto:

 A razredpredstavljanjeaavtopredmet.
 Lastnosti:
 kilometrina (float): trenutna kilometrina avtomobila.
 Metode:
 vožnja (milje): vozi avto za določeno število milj.

def__v__(sam, kilometrina):
 self.mileage = kilometrina
defpogon(jaz, milje):

 Vozi avto za določeno število milj.
 Argi:
 milje (float): Število milj za prevoz.
 Vrne:
Noben

 samo.kilometrina += milj

Niz dokumentov za zgornji razred opisuje, kaj razred predstavlja, njegove atribute in metode. Medtem nizi dokumentov za pogonsko metodo zagotavljajo informacije o tem, kaj metoda počne, argumente, ki jih pričakuje, in kaj vrne.

Tako vsakdo, ki dela s tem razredom, lažje razume, kako ga uporabljati. Druge prednosti uporabe nizov dokumentov vključujejo:

• Možnost vzdrževanja kode: nizi dokumentov z jasnim opisom delovanja kode pomagajo razvijalcem spreminjati in posodabljati kodo brez vnašanja napak.
• Lažje sodelovanje: ko več razvijalcev sodeluje na isti osnovi kode – na primer z Orodje za skupno rabo v živo Visual Studio— nizi dokumentov omogočajo razvijalcem, da dosledno dokumentirajo kodo, tako da jo lahko razumejo vsi v ekipi.
• Izboljšana berljivost kode: nizi dokumentov nudijo povzetek na visoki ravni o tem, kaj počne koda, kar omogoča vsakomur, ki bere kodo, da hitro razume njen namen, ne da bi šel skozi celotno kodo blok.

Formati nizov dokumentov

Dober niz dokumentov bi moral opisovati, kaj počne del kode, argumente, ki jih pričakuje, in podrobnosti izvedbe, če je potrebno. Vključevati mora zlasti vse robne primere, ki bi se jih morali zavedati vsi, ki uporabljajo kodo.

Osnovni format niza dokumentov ima naslednje razdelke:

• Vrstica povzetka: enovrstični povzetek tega, kar počne koda.
• Argumenti: Informacije o argumentih, ki jih funkcija pričakuje, vključno z njihovimi vrstami podatkov.
• Povratna vrednost: Informacije o vrnjeni vrednosti funkcije, vključno z njenim podatkovnim tipom.
• Povišanja (neobvezno): informacije o morebitnih izjemah, ki jih lahko sproži funkcija.

To je samo osnovni format, saj lahko izberete druge formate za osnovo nizov dokumentov. Najbolj priljubljeni so Epytext, reStructuredText (znan tudi kot reST), NumPy in Google docstrings. Vsak od teh formatov ima svojo sintakso, kot je prikazano v naslednjih primerih:

Epytext

Niz dokumenta, ki sledi formatu Epytext:

defpomnožiti(a, b):

 Pomnožite dve števili skupaj.
 @param a: prvo število za množenje.
 @tip a: int
 @param b: drugo število za množenje.
 @tip b: int
 @return: zmnožek dveh števil.
 @rtype: int

vrnitev a * b

reStructuredText (reST)

Niz dokumenta, ki sledi formatu reST:

defpomnožiti(a, b):

 Pomnožite dve števili skupaj.
 :param a: Prvo število za množenje.
 :tip a: int
 :param b: Drugo število za množenje.
 :tip b: int
 :vrnitev: zmnožek dveh števil.
 :rtype: int

vrnitev a * b

NumPy

Niz dokumenta, ki sledi formatu NumPy:

defpomnožiti(a, b):

 Pomnožite dve števili skupaj.
 Parametri

 a: notr
 Prvo število za množenje.
 b: notr
 Drugo število za množenje.
 Vračila

 int
 Zmnožek dveh števil.

vrnitev a * b

Google

Niz dokumenta, ki sledi Googlovi obliki:

defpomnožiti(a, b):

 Pomnožite dve števili skupaj.
 Argi:
 a (int): prvo število za množenje.
 b (int): drugo število za množenje.
 Vrne:
 int: zmnožek dveh števil.

vrnitev a * b

Čeprav vsi štirje formati nizov dokumentov nudijo uporabno dokumentacijo za funkcijo množenja, sta formata NumPy in Google lažje brati kot formata Epytext in reST.

Kako vključiti teste v nize dokumentov

Primere testiranja lahko vključite v nize dokumentov z uporabo modula doctest. Modul doctest išče v nizu dokumentov besedilo, ki je videti kot interaktivne seje Python, in jih nato izvede, da preveri, ali delujejo, kot bi morale.

Če želite uporabiti teste dokumentov, vključite vzorčne vnose in pričakovane rezultate v niz dokumentov. Spodaj je primer, kako bi to storili:

defpomnožiti(a, b):

 Pomnožite dve števili skupaj.
 Parametri

 a: notr
 Prvo število za množenje.
 b: notr
 Drugo število za množenje.
 Vračila

 int
 Zmnožek dveh števil.
 Primeri

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

vrnitev a * b

The Primeri razdelek vsebuje tri klice funkcij z različnimi argumenti in podaja pričakovani rezultat za vsakega. Ko zaženete modul doctest, kot je prikazano spodaj, bo izvedel primere in primerjal dejanski rezultat s pričakovanim rezultatom.

python -m doctest multiply.py

Če obstajajo razlike, jih modul doctest sporoči kot napake. Uporaba doctestov z nizi dokumentov, kot je ta, vam pomaga preveriti, ali koda deluje po pričakovanjih. Upoštevajte, da doctests niso nadomestilo za obsežnejše enotni testi in integracijski testi za vašo kodo Python.

Kako ustvariti dokumentacijo iz nizov dokumentov

Naučili ste se osnov uporabe nizov dokumentov za dokumentiranje vaše kode Python in pomena visokokakovostne dokumentacije. Če želite to narediti še višje, boste morda želeli ustvariti dokumentacijo za svoje module in funkcije iz njihovih ustreznih nizov dokumentov.

Eden najbolj priljubljenih generatorjev dokumentacije, ki ga lahko uporabite, je Sphinx. Privzeto podpira format dokumentov reST, vendar ga lahko konfigurirate za delo z formatom Google ali NumPy.