Cum să documentați codul Python folosind Docstrings

Fără o documentație adecvată, poate fi dificil să înțelegeți, să întrețineți și să vă depanați codul. În Python, puteți folosi docstrings pentru a oferi descrieri concise și exemple despre cum funcționează codul.

Ce sunt Docstrings?

Docstring-urile sunt șiruri pe care le puteți adăuga la codul dvs. Python pentru a explica ce face și cum să le utilizați. Piesa de cod poate fi a Funcția Python, un modul sau o clasă.

Docstrings seamănă foarte mult cu comentariile standard Python, dar au unele diferențe. Comentariile Python oferă dezvoltatorilor informații suplimentare despre funcționarea interioară a codului, cum ar fi detalii de implementare sau avertismente de reținut atunci când extindeți codul.

Pe de altă parte, docstring-urile oferă în mare parte informații utilizatorilor codului care nu trebuie neapărat să cunoască detaliile implementării acestuia, dar trebuie să înțeleagă ce face și cum să-l folosească.

Cum se scrie Docstrings

De obicei, includeți documente la începutul blocului de cod pe care doriți să îl documentați. Trebuie să le includeți între ghilimele triple (). Puteți scrie șiruri de documente cu o singură linie sau șiruri de documente cu mai multe rânduri.

Docstring-urile cu o singură linie sunt potrivite pentru codul simplu care nu necesită multă documentație.

Mai jos este un exemplu de funcție numită înmulțire. Docstring explică că funcția de multiplicare ia două numere, le multiplică și returnează rezultatul.

defmultiplica(a, b):
Înmulțește două numere și returnează rezultatul
întoarcere a * b

Utilizați documente cu mai multe linii pentru un cod mai complex care necesită documentație detaliată.

Luați în considerare următoarea clasă de mașini:

clasăMașină:

 A clasăreprezentândAmașinăobiect.
 Atribute:
 kilometraj (float): kilometrajul curent al mașinii.
 Metode:
 conduce (mile): conduce mașina pentru numărul specificat de mile.

def__init__(auto, kilometraj):
 self.mileage = kilometraj
defconduce(auto, mile):

 Conduce mașina pentru numărul specificat de mile.
 Argumente:
 mile (float): numărul de mile de parcurs.
 Se intoarce:
Nici unul

 self.mileage += mile

Docstring pentru clasa de mai sus descrie ceea ce reprezintă clasa, atributele și metodele sale. Între timp, docstring-urile pentru metoda drive oferă informații despre ce face metoda, argumentele pe care le așteaptă și ce returnează.

Acest lucru face mai ușor pentru oricine care lucrează cu această clasă să înțeleagă cum să o folosească. Celelalte beneficii ale utilizării documentelor includ:

• Menținerea codului: oferind o descriere clară a modului în care funcționează codul, documentele ajută dezvoltatorii să modifice și să actualizeze codul fără a introduce erori.
• Colaborare mai ușoară: atunci când mai mulți dezvoltatori colaborează pe aceeași bază de cod, de exemplu, cu Instrument de partajare live Visual Studio—docstring-urile permit dezvoltatorilor să documenteze codul în mod consecvent, astfel încât toată lumea din echipă să-l poată înțelege.
• Lizibilitate îmbunătățită a codului: Docstring-urile oferă un rezumat la nivel înalt a ceea ce permite codul oricine citește codul să-și înțeleagă rapid scopul fără a parcurge întregul cod bloc.

Formate Docstring

Un docstring bun ar trebui să descrie ceea ce face o bucată de cod, argumentele pe care le așteaptă și detalii de implementare, dacă este necesar. Ar trebui să includă în special cazurile marginale de care ar trebui să le cunoască oricine care utilizează codul.

Un format docstring de bază are următoarele secțiuni:

• Linie rezumat: un rezumat pe o linie a ceea ce face codul.
• Argumente: informații despre argumentele pe care funcția le așteaptă, inclusiv tipurile lor de date.
• Valoarea returnată: informații despre valoarea returnată a funcției, inclusiv tipul de date.
• Creșteri (opțional): informații despre orice excepții pe care funcția le poate ridica.

Acesta este doar un format de bază, deoarece există și alte formate pe care le puteți alege pentru a vă baza documentele. Cele mai populare sunt Epytext, reStructuredText (cunoscut și sub numele de reST), NumPy și Google docstrings. Fiecare dintre aceste formate are propria sa sintaxă, așa cum se arată în următoarele exemple:

Epytext

Un șir documentar care urmează formatul Epytext:

defmultiplica(a, b):

 Înmulțiți două numere împreună.
 @param a: primul număr de înmulțit.
 @type a: int
 @param b: Al doilea număr de înmulțit.
 @tipul b: int
 @return: produsul celor două numere.
 @rtype: int

întoarcere a * b

Text reStructurat (reST)

Un docstring care urmează formatul reST:

defmultiplica(a, b):

 Înmulțiți două numere împreună.
 :param a: Primul număr de înmulțit.
 :type a: int
 :param b: Al doilea număr de înmulțit.
 :tip b: int
 :întoarcere: produsul celor două numere.
 :rtype: int

întoarcere a * b

NumPy

Un docstring care urmează formatul NumPy:

defmultiplica(a, b):

 Înmulțiți două numere împreună.
 Parametrii

 a: int
 Primul număr de înmulțit.
 b: int
 Al doilea număr de înmulțit.
 Se intoarce

 int
 Produsul celor două numere.

întoarcere a * b

Google

Un docstring care urmează formatul Google:

defmultiplica(a, b):

 Înmulțiți două numere împreună.
 Argumente:
 a (int): primul număr de înmulțit.
 b (int): al doilea număr de înmulțit.
 Se intoarce:
 int: produsul celor două numere.

întoarcere a * b

Deși toate cele patru formate de documente oferă documentație utilă pentru funcția de multiplicare, formatele NumPy și Google sunt mai ușor de citit decât formatele Epytext și reST.

Cum să includeți teste în Docstrings

Puteți include exemple de testare în docstrings folosind modulul doctest. Modulul doctest caută în șirul documentar text care arată ca sesiuni Python interactive și apoi le execută pentru a verifica dacă funcționează așa cum ar trebui.

Pentru a utiliza doctests, includeți eșantionul de intrare și ieșirile așteptate în docstring. Mai jos este un exemplu despre cum ați face asta:

defmultiplica(a, b):

 Înmulțiți două numere împreună.
 Parametrii

 a: int
 Primul număr de înmulțit.
 b: int
 Al doilea număr de înmulțit.
 Se intoarce

 int
 Produsul celor două numere.
 Exemple

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

întoarcere a * b

The Exemple secțiunea conține trei apeluri de funcție cu argumente diferite și specifică rezultatul așteptat pentru fiecare. Când rulați modulul doctest așa cum se arată mai jos, acesta va executa exemplele și va compara rezultatul real cu rezultatul așteptat.

python -m doctest multiplicare.py

Dacă există diferențe, modulul doctest le raportează ca eșecuri. Folosirea doctest-urilor cu docstring-uri ca acesta vă ajută să verificați dacă codul funcționează conform așteptărilor. Rețineți că doctestele nu sunt un înlocuitor pentru mai cuprinzătoare teste unitare și teste de integrare pentru codul dvs. Python.

Cum se generează documentație din Docstrings

Ați învățat elementele de bază ale utilizării documentelor pentru a vă documenta codul Python și importanța documentației de înaltă calitate. Pentru a trece la un nivel superior, poate doriți să generați documentație pentru modulele și funcțiile dvs. din șirurile de documente respective.

Unul dintre cele mai populare generatoare de documente pe care le puteți folosi este Sphinx. Acceptă formatul reST docstring în mod implicit, dar îl puteți configura să funcționeze cu formatul Google sau NumPy.