Pythoni koodi dokumenteerimine dokumentide stringide abil

Ilma korraliku dokumentatsioonita võib koodi mõistmine, hooldamine ja silumine olla keeruline. Pythonis saate kasutada dokstringe, et pakkuda koodi toimimise kohta lühikesi kirjeldusi ja näiteid.

Mis on Docstringid?

Docstringid on stringid, mille saate oma Pythoni koodile lisada, et selgitada, mida see teeb ja kuidas seda kasutada. Kooditükk võib olla a Pythoni funktsioon, moodul või klass.

Docstringid näevad välja nagu tavalised Pythoni kommentaarid, kuid neil on mõned erinevused. Pythoni kommentaarid annavad arendajatele lisateavet koodi sisemise toimimise kohta, näiteks juurutamise üksikasjad või hoiatused, mida koodi laiendamisel meeles pidada.

Teisest küljest pakuvad dokumendistringid enamasti teavet koodi kasutajatele, kes ei pruugi tingimata teada selle rakendamise üksikasju, kuid peavad mõistma, mida see teeb ja kuidas seda kasutada.

Kuidas kirjutada dokumente

Tavaliselt lisate dokumendistringid selle koodiploki algusesse, mida soovite dokumenteerida. Peate need lisama kolmekordsetesse jutumärkidesse (). Saate kirjutada üherealisi või mitmerealisi dokumente.

Üherealised dokumendistringid sobivad lihtsa koodi jaoks, mis ei nõua palju dokumentatsiooni.

Allpool on näide funktsioonist nimega korrutamine. Dokumendistring selgitab, et korrutamisfunktsioon võtab kaks arvu, korrutab need ja tagastab tulemuse.

defkorrutada(a, b):
Korrutab kaks arvu ja tagastab tulemuse
tagasi a * b

Keerulisema koodi jaoks, mis vajab üksikasjalikku dokumentatsiooni, kasutage mitmerealisi dokumente.

Mõelge järgmistele autoklassidele:

klassAuto:

 A klassesindavadaautoobjektiks.
 Atribuudid:
 läbisõit (float): auto praegune läbisõit.
 Meetodid:
 sõita (miili): juhib autot jaoks määratud arv miile.

def__selles__(ise, läbisõit):
 ise.kilometraaž = läbisõit
defsõita(ise, miilid):

 Juhib autot jaoks määratud arv miile.
 Args:
 miilid (ujuk): läbitud miilide arv.
 Tagastab:
Mitte ühtegi

 ise.läbisõit += miili

Ülaltoodud klassi dokumendistring kirjeldab, mida klass esindab, selle atribuute ja meetodeid. Samal ajal annavad draivi meetodi dokumendistringid teavet selle kohta, mida meetod teeb, milliseid argumente see ootab ja mida see tagastab.

Nii on kõigil selle klassiga töötavatel inimestel lihtsam mõista, kuidas seda kasutada. Dokumendistringide kasutamise muud eelised on järgmised:

• Koodi hooldatavus: pakkudes koodi toimimise selget kirjeldust, aitavad dokumendistringid arendajatel koodi muuta ja värskendada ilma vigu tekitamata.
• Lihtsam koostöö: kui mitu arendajat teevad koostööd sama koodibaasiga, näiteks koos Visual Studio reaalajas jagamise tööriist-dokstringid võimaldavad arendajatel koodi järjepidevalt dokumenteerida, et kõik meeskonnaliikmed sellest aru saaksid.
• Täiustatud koodi loetavus: Docstringid annavad kõrgetasemelise kokkuvõtte sellest, mida kood teeb, mis võimaldab igaüks, kes loeb koodi, et kiiresti mõista selle eesmärki ilma kogu koodi läbi vaatamata blokk.

Docstringi vormingud

Hea dokstring peaks kirjeldama, mida koodilõik teeb, milliseid argumente see eeldab ja vajadusel rakenduse üksikasju. See peaks eelkõige hõlmama kõiki servajuhtumeid, millest igaüks, kes koodi kasutab, peaks teadma.

Põhilisel dokumendistringi vormingul on järgmised jaotised.

• Kokkuvõtte rida: üherealine kokkuvõte selle kohta, mida kood teeb.
• Argumendid: teave argumentide kohta, mida funktsioon eeldab, sealhulgas nende andmetüübid.
• Tagastusväärtus: teave funktsiooni tagastatava väärtuse kohta, sealhulgas selle andmetüüp.
• Tõstab (valikuline): teave kõigi erandite kohta, mida funktsioon võib esile kutsuda.

See on vaid põhivorming, kuna on ka teisi vorminguid, mille saate oma dokumendistringi aluseks võtta. Kõige populaarsemad on Epytext, reStructuredText (tuntud ka kui reST), NumPy ja Google'i dokumendistringid. Igal neist vormingutest on oma süntaks, nagu on näidatud järgmistes näidetes.

Epütekst

Dokumendistring, mis järgib Epytext vormingut:

defkorrutada(a, b):

 Korrutage kaks arvu kokku.
 @param a: esimene arv, mida korrutada.
 @type a: int
 @param b: teine ​​arv, mida korrutada.
 @tüüp b: int
 @return: kahe arvu korrutis.
 @rtype: int

tagasi a * b

reStructuredText (reST)

Dokumendistring, mis järgib vormingut reST:

defkorrutada(a, b):

 Korrutage kaks arvu kokku.
 :param a: Esimene arv, mida korrutada.
 :type a: int
 :param b: teine ​​arv korrutamiseks.
 :tüüp b: int
 :tagasi: kahe arvu korrutis.
 :rtype: int

tagasi a * b

NumPy

Dokumendistring, mis järgib NumPy vormingut:

defkorrutada(a, b):

 Korrutage kaks arvu kokku.
 Parameetrid

 a: int
 Esimene arv, mida korrutada.
 b: int
 Teine arv korrutamiseks.
 Tagastab

 int
 Kahe arvu korrutis.

tagasi a * b

Google

Dokumendistring, mis järgib Google'i vormingut:

defkorrutada(a, b):

 Korrutage kaks arvu kokku.
 Args:
 a (int): esimene arv, mida korrutada.
 b (int): teine ​​arv, mida korrutada.
 Tagastab:
 int: kahe arvu korrutis.

tagasi a * b

Kuigi kõik neli dokumendistringi vormingut pakuvad kasulikku dokumentatsiooni korrutamisfunktsiooni jaoks, on NumPy ja Google'i vorminguid lihtsam lugeda kui Epytext- ja reST-vorminguid.

Kuidas lisada teste dokumendistringidesse

Saate lisada oma dokstringidesse testimise näiteid, kasutades doktesti moodulit. Moodul doctest otsib dokstringist teksti, mis näeb välja nagu interaktiivsed Pythoni seansid, ja seejärel käivitab need, et kontrollida, kas need töötavad nii nagu peaks.

Doktestide kasutamiseks lisage dokumendistringi näidissisendid ja eeldatavad väljundid. Allpool on näide selle kohta, kuidas seda teha.

defkorrutada(a, b):

 Korrutage kaks arvu kokku.
 Parameetrid

 a: int
 Esimene arv, mida korrutada.
 b: int
 Teine arv korrutamiseks.
 Tagastab

 int
 Kahe arvu korrutis.
 Näited

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

tagasi a * b

The Näited jaotis sisaldab kolme erinevate argumentidega funktsioonikutset ja määrab igaühe jaoks eeldatava väljundi. Kui käivitate mooduli doctest, nagu allpool näidatud, käivitab see näited ja võrdleb tegelikku väljundit eeldatava väljundiga.

python -m doctest multiply.py

Kui esineb erinevusi, teatab doktesti moodul need tõrgetest. Doktestide kasutamine selliste dokumentide stringidega aitab teil kontrollida, kas kood töötab ootuspäraselt. Pange tähele, et doktorid ei asenda kõikehõlmavamat teie Pythoni koodi ühikutestid ja integratsioonitestid.

Kuidas luua dokumentatsiooni Docsstringidest

Olete õppinud Pythoni koodi dokumenteerimiseks docstringide kasutamise põhitõdesid ja kvaliteetse dokumentatsiooni tähtsust. Selle paremaks muutmiseks võiksite luua oma moodulite ja funktsioonide dokumentatsiooni nende vastavatest dokumentidest.

Üks populaarsemaid dokumentide generaatoreid, mida saate kasutada, on Sphinx. See toetab vaikimisi reST docstringi vormingut, kuid saate selle konfigureerida töötama Google'i või NumPy vorminguga.