Com que ja sabem com escriure els comentaris multilínia, podem utilitzar les cometes simples triples o les cometes dobles triples. Utilitzem una cadena de documentació quan volem descriure les nostres funcions perquè puguem obtenir la documentació quan la necessitem. Alguns IDE us ofereixen documentació només passant el cursor per sobre del nom i alguns destaquen determinades paraules clau. Però el fet és que les cadenes de documents a NumPy són molt més flexibles que en altres idiomes. Docstring és un literal de cadena que es produeix a l'inici de la definició de la funció. Hem de proporcionar valors específics mentre utilitzem les docstrings en casos de funcions, classes, etc.
Quan utilitzem docstrings amb funcions, hem de passar els arguments. Quan les utilitzem amb classes, passem els atributs i mètodes. En el cas dels Mòduls, hem de proporcionar una llista de classes i funcions. En el cas del paquet, passem la llista de mòduls amb funcionalitat. Així, bàsicament, el propòsit de la cadena de documents és, com el seu nom explica, que ajudi amb la documentació del nostre codi. Fem documentació perquè si algú fa servir el nostre codi en el futur, serà capaç d'entendre el nostre codi i la lògica que hi ha darrere del nostre codi amb l'ajuda de docstring. Les funcions integrades també tenen docstrings; podem utilitzar la funció d'ajuda () per mirar la cadena de documents de les funcions integrades.
Hi ha algunes diferències entre els comentaris i les cadenes de documents. Els intèrprets ignoren els comentaris, però els intèrprets no ignoren les cadenes de documents. S'assigna memòria per a les cadenes de documents. Un comentari és una descripció del codi però, d'altra banda, les cadenes de documents ens indiquen el propòsit del codi.
Sintaxi:
La sintaxi per escriure les cadenes de documents a NumPy és:
'''Missatge de documentació'''
O
'''Missatge Docstring'''
Tingueu en compte que docstring no és una funció o mètode, de manera que no té la sintaxi adequada. L'únic que cal tenir en compte aquí és que comencem la cadena de documents amb tres cometes simples o tres cometes dobles. Escrivim la nostra descripció del codi i tornem a acabar amb tres cometes simples o tres cometes dobles al final. No hi ha cap cosa obligatòria per escriure per a les cadenes de documents. Només has de posar tres cometes simples o dobles abans i després de la descripció de la cadena.
Exemple 1:
Per entendre millor les cadenes de documents, fem un exemple. En aquest exemple, després d'incloure la biblioteca NumPy, simplement declarem la variable 'a' i una altra variable 'b'. Després d'això, creem la nostra docstring que diu 'Afegim variables 'a' i 'b'. En el nostre cas, aquest és un exemple fàcil, però si el nostre codi és complex, això ajuda molt el programador a entendre el codi. Després d'això, sumem les variables 'a' i 'b' i emmagatzemem el seu resultat de sortida en una altra variable que és 'c'. Finalment, imprimim el valor de la variable “c”. Ara, executem el nostre codi.
importar numpy com per exemple.a = 1
b = 2
'''Afegim variables a i b'''
c = a+b
imprimir ( c )
Aquesta és la nostra sortida de la peça de codi donada. Podem veure que el sistema no ha donat cap error sobre la sintaxi incorrecta ni res per a la línia 7 del nostre codi. A més, el sistema no ha imprès la nostra cadena de documents. En canvi, només va imprimir la sortida de la nostra variable 'c' en la qual vam dir al nostre sistema que imprimís. Això mostra com funcionen les cadenes de documents. La propera vegada, quan un programador nou intenti treballar amb el nostre codi, entendrà què estem fent amb l'ajuda de la nostra docstring. Però no s'imprimirà com a sortida, de manera que l'usuari del codi no es veurà molestat.
Exemple 2:
Ara, realitzem un exemple complex per entendre el funcionament de la cadena de documents. Primer, incloem la biblioteca NumPy i després escrivim una cadena de document en la qual expliquem la següent línia de codi on expliquem la inicialització de la matriu. També afegim les docstrings a l'altra part del codi. Ara, si compartim aquest codi amb qualsevol desenvolupador de Python nou sense afegir les cadenes de documents, d'alguna manera li serà difícil conèixer el funcionament i el propòsit d'aquest codi. Primer ha de buscar les funcions que hem utilitzat. Però si afegim una cadena de documents al nostre codi, serà fàcil que els altres desenvolupadors entenguin el codi sense estudiar més sobre les funcions. No ens limitem a afegir comentaris fins a alguns límits; els comentaris poden ser d'una o més d'una línia. També es pot afegir més d'una vegada en un codi. A continuació, importeu NumPy com a np.
'''Creant la variable a la qual passarem una matriu de mida 1x6'''matriu = per exemple. matriu ( [ 11 , 22 , 33 , 44 , 55 , 66 ] )
'''assignar la matriu a la funció tofile() per deixar-la desar al fitxer anomenat arr'''
matriu . arxivar ( 'arr.bin' )
'''Mostra el fitxer amb la funció fromfile'''
imprimir ( per exemple. fromfile ( 'arr.bin' , dtype = int ) )
Com es mostra al fragment següent, les cadenes de documents no es mostren a la sortida, la qual cosa significa que no afecta la sortida o la compilació del codi. Les cadenes de documents s'ignoren durant el procés de compilació.
Conclusió
En aquesta guia, hem après sobre docstrings a NumPy. Vam comparar les cadenes de documents amb els comentaris i vam explicar la diferència entre tots dos. Hem après la sintaxi de les cadenes de documents i com escriure-les al nostre codi. A més, també hem intentat explicar què són les docstrings a NumPy i com funcionen amb l'ajuda d'exemples. Finalment, vam remarcar que són essencials per als codificadors. No repetirem la importància de les docstrings a NumPy. Només direm que hauríeu d'utilitzar les cadenes de documents al vostre codi. A NumPy, l'estil d'escriptura de docstrings és el més popular. S'utilitza àmpliament a la comunitat de programació per informar-se mútuament del funcionament i la funcionalitat dels seus codis. Aquesta guia us ajudarà a començar amb les cadenes de documents NumPy. Hem intentat cobrir la major part del que necessitareu utilitzant les docstrings de NumPy.