Deoarece știm deja cum să scriem comentariile pe mai multe linii, putem folosi fie ghilimele simple, fie ghilimele triple. Folosim un șir de documentație atunci când dorim să descriem funcțiile noastre, astfel încât să putem obține documentația atunci când avem nevoie de ea. Unele IDE-uri vă oferă documentație doar trecând peste nume, iar unele evidențiază anumite cuvinte cheie. Dar adevărul este că documentele din NumPy sunt mult mai flexibile decât în alte limbi. Docstring este un șir literal care apare la începutul definiției funcției. Trebuie să furnizăm valori specifice în timp ce folosim docstring-urile în cazuri de funcții, clase etc.
Când folosim docstring-uri cu funcții, trebuie să transmitem argumentele. Când le folosim cu clase, transmitem atributele și metodele. În cazul modulelor, trebuie să oferim o listă de clase și funcții. În cazul pachetului, trecem lista de module cu funcționalitate. Deci, practic, scopul docstring-ului este, după cum explică și numele, acela de a ajuta la documentarea codului nostru. Facem documentație, astfel încât, dacă cineva va folosi codul nostru în viitor, el va putea înțelege codul nostru și logica din spatele codului nostru cu ajutorul docstring. Funcțiile încorporate au și docstring-uri în ele; putem folosi funcția help() pentru a analiza șirul de documente al funcțiilor încorporate.
Există câteva diferențe între comentarii și documente. Comentariile sunt ignorate de interpreți, dar documentele nu sunt ignorate de interpreți. Memoria este alocată pentru documente. Un comentariu este o descriere a codului, dar pe de altă parte, documentele ne spun scopul codului.
Sintaxă:
Sintaxa pentru a scrie docstrings în NumPy este:
'''Mesaj Docstring'''
Sau
'''Mesaj Docstring'''
Vă rugăm să rețineți că docstring nu este o funcție sau o metodă, deci nu are o sintaxă adecvată. Singurul lucru de remarcat aici este că începem documentul cu trei ghilimele simple sau trei ghilimele duble. Scriem descrierea codului și o încheiem din nou cu trei ghilimele simple sau trei ghilimele duble la sfârșit. Nu există un lucru obligatoriu de scris pentru docstrings. Trebuie doar să puneți trei ghilimele simple sau duble înainte și după descrierea șirului.
Exemplul 1:
Pentru a înțelege mai bine documentele, haideți să facem un exemplu. În acest exemplu, după ce includem biblioteca NumPy, pur și simplu declarăm variabila „a” și o altă variabilă „b”. După aceea, creăm șirul nostru document care spune „Să adăugăm variabilele „a” și „b”. În cazul nostru, acesta este un exemplu ușor, dar dacă codul nostru este complex, acest lucru îl ajută foarte mult pe programator să înțeleagă codul. După aceea, însumăm variabilele „a” și „b” și stocăm rezultatul lor de ieșire într-o altă variabilă care este „c”. În cele din urmă, imprimăm valoarea variabilei „c”. Acum, executăm codul nostru.
import numpy la fel de de exemplu.A = 1
b = Două
'''Să adăugăm variabilele a și b'''
c = a+b
imprimare ( c )
Aceasta este rezultatul nostru din fragmentul de cod dat. Putem vedea că sistemul nu a dat nicio eroare cu privire la sintaxa incorectă sau nimic pentru linia 7 a codului nostru. De asemenea, sistemul nu a tipărit documentul nostru. În schimb, a tipărit doar rezultatul variabilei noastre „c” în care am spus sistemului nostru să imprime. Aceasta arată cum funcționează documentele. Data viitoare, când un nou programator încearcă să lucreze la codul nostru, el va înțelege ce facem cu ajutorul docstring-ului nostru. Dar nu va fi tipărit ca rezultat, astfel încât utilizatorul codului nu va fi deranjat de acesta.
Exemplul 2:
Acum, efectuăm un exemplu complex pentru a înțelege funcționarea documentului. Mai întâi, includem biblioteca NumPy și apoi scriem un șir de documente în care explicăm următoarea linie de cod în care explicăm inițializarea matricei. Adăugăm și docstring-urile în cealaltă parte a codului. Acum, dacă împărtășim acest cod cu orice nou dezvoltator Python fără a adăuga documentele, îi va fi cumva dificil să cunoască funcționarea și scopul acestui cod. El trebuie să caute mai întâi despre funcțiile pe care le-am folosit. Dar dacă adăugăm un docstring la codul nostru, va fi ușor pentru ceilalți dezvoltatori să înțeleagă codul fără a studia mai mult despre funcții. Nu ne limităm la a adăuga comentarii la anumite limite; comentariile pot avea una sau mai multe rânduri. De asemenea, poate fi adăugat de mai multe ori într-un cod. Apoi, importați NumPy ca np.
'''Crearea variabilei căreia îi vom transmite o matrice de dimensiune 1x6'''matrice = de exemplu. matrice ( [ unsprezece , 22 , 33 , 44 , 55 , 66 ] )
'''atribuirea matricei la funcția tofile() pentru a-l lăsa salvat în fișierul numit arr'''
matrice . la dosar ( 'arr.bin' )
'''afișează fișierul folosind funcția fromfile'''
imprimare ( de exemplu. din fisier ( 'arr.bin' , dtype = int ) )
După cum se arată în următorul fragment, documentele nu sunt afișate în rezultat, ceea ce înseamnă că nu afectează rezultatul sau compilarea codului. Docstrings sunt ignorate în timpul procesului de compilare.
Concluzie
În acest ghid, am învățat despre docstrings în NumPy. Am comparat documentele cu comentarii și am explicat diferența dintre ambele. Am învățat sintaxa docstring-urilor și cum să scriem docstring-urile în codul nostru. În plus, am încercat să explicăm ce sunt șirurile documentare din NumPy și cum funcționează cu ajutorul exemplelor. În cele din urmă, am remarcat că acestea sunt esențiale pentru programatori. Nu vom repeta importanța docstring-urilor în NumPy. Vom spune doar că ar trebui să utilizați docstring-urile din codul dvs. În NumPy, stilul de scriere al documentelor este cel mai popular. Este utilizat pe scară largă în comunitatea de programare pentru a se informa reciproc despre funcționarea și funcționalitatea codurilor lor. Acest ghid vă va ajuta să începeți cu NumPy docstrings. Am încercat să acoperim cea mai mare parte a ceea ce veți avea nevoie folosind documentele din NumPy.